Back to top

NameCoach Integration API v3

This API is used to integrate name pronunciation recordings with displayed names and profiles of members of your organization (employees, faculty, staff, students, etc.)

Typical online systems in which name pronunciation recordings are embedded include:

  • Private or Public Directory
  • SIS (Student Information System)
  • LMS (Learning Management System)
  • HCM (Human Capital Management) System
  • CRM (Customer Relationship Management) System

Endpoint:  https://www.name-coach.com/api/private/v3/names


Parameters Description

Note

  • The access_code 1-to-1 maps to a Name Page (see demo Name Page). After subscribed to our Integration Service, you will get an access code that retrieves name recordings for all members of your institution (not just those on a given Name Page.)
Create API token

Parameters

  • auth_token: the authentication token to access to private API

  • access_code: the access code for a Name Page (required parameter)

  • email: an email of a particular individual whose name recording you want to retrieve (optional parameter)

  • institution_id: an internal school id, provided by users import (optional parameter)

  • include_extended_attributes: that param's presence / value controls whether or not custom attribute values are returned in the response. (optional parameter)

  • icon: an icon identifier for embed_image response option (optional parameter)

    • 0 - Playbutton (default)
    • 1 - Speaker 32px
    • 2 - Spkr2

  • play_button_img_url: an image url for embed_image response option (optional parameter)

Requests

Note

Every JSON response includes 4 options for embedding name recordings:

  • embed_image - play button or speaker button image that plays an audio name recording when clicked

  • embed_iframe - iframe to a lightweight playbutton that plays an audio name recording when clicked

  • recording_link - link that plays an audio name recording in a web browser

  • name_badge_link - link to a Namebadge containing the audio name recording and other cultural information about this individual

(For example renderings, see API Documentation Resources.)


To retrieve all name recordings from a Name Page:

GET/?auth_token={auth_token}&access_code={access_code}

Parameters
HideShow
auth_token
string (required) - the authentication token to access to private API 

Example: FjQB7vXvsPK_Ur6swRk7

access_code
string (required) - access code for a Name Page 

Example: example-237eyc55

include_extended_attributes
boolean (optional) - specify behaviour of receiving custom attribute values 

Example:  true

Example (cURL) 
curl --header "Content-Type: application/json" "https://name-coach.com/api/private/v3/names?access_code=example-237eyc55&auth_token=FjQB7vXvsPK_Ur6swRk7"
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": "success",
  "data": [
    {
      "first_name": "Oluwarotimi",
      "last_name": "Adesina",
      "email": "oluwarotimi-adesina@example.com",
      "embed_image": "\u003cimg alt=\"Playbutton 9814faf2f7896737e991d283f48914d0177804a8cd8d605a7321abd15c0832b1\" height=\"15\" onclick=\"javascript:(function() {\n  var audio = document.createElement(\u0026#39;audio\u0026#39;);\n  audio.src = \u0026quot;https://namewaves.s3.amazonaws.com/502.mp3?digest=38506\u0026quot;;\n  audio.play();\n}).call();\n\" src=\"https://name-coach.com/images/playbutton-9814faf2f7896737e991d283f48914d0177804a8cd8d605a7321abd15c0832b1.png\" width=\"15\" /\u003e",
      "embed_iframe": "\u003ciframe frameborder='0' height='40' src='https://name-coach.com/playbutton/d9f2720effc29fa9075a4526fd5e20ea19d9e228' width='40'\u003e\u003c/iframe\u003e",
      "recording_link": "https://namewaves.s3.amazonaws.com/1980_2124_6C854.mp3",
      "name_badge_link": "http://www.name-coach.com/oluwarotimiadesina"
    },
    {
      "first_name": "Karla",
      "last_name": "Gleichauf",
      "email": "karla-gleichauf@example.com",
      "embed_image": "\u003cimg alt=\"Playbutton 9814faf2f7896737e991d283f48914d0177804a8cd8d605a7321abd15c0832b1\" height=\"15\" onclick=\"javascript:(function() {\n  var audio = document.createElement(\u0026#39;audio\u0026#39;);\n  audio.src = \u0026quot;https://namewaves.s3.amazonaws.com/1980_2124_6C854.mp3?digest=38507\u0026quot;;\n  audio.play();\n}).call();\n\" src=\"https://name-coach.com/images/playbutton-9814faf2f7896737e991d283f48914d0177804a8cd8d605a7321abd15c0832b1.png\" width=\"15\" /\u003e",
      "embed_iframe": "\u003ciframe frameborder='0' height='40' src='https://name-coach.com/playbutton/14b4a292fc9034ff65bb2523412282d71e4251ce' width='40'\u003e\u003c/iframe\u003e",
      "recording_link": "https://namewaves.s3.amazonaws.com/19.mp3",
      "name_badge_link": "http://www.name-coach.com/karlagleichauf"
    },
    {
      "first_name": "Sindura",
      "last_name": "Ravichandran",
      "email": "sindura-ravichandran@example.com",
      "embed_image": "\u003cimg alt=\"Playbutton 9814faf2f7896737e991d283f48914d0177804a8cd8d605a7321abd15c0832b1\" height=\"15\" onclick=\"javascript:(function() {\n  var audio = document.createElement(\u0026#39;audio\u0026#39;);\n  audio.src = \u0026quot;https://namewaves.s3.amazonaws.com/19.mp3?digest=38508\u0026quot;;\n  audio.play();\n}).call();\n\" src=\"https://name-coach.com/images/playbutton-9814faf2f7896737e991d283f48914d0177804a8cd8d605a7321abd15c0832b1.png\" width=\"15\" /\u003e",
      "embed_iframe": "\u003ciframe frameborder='0' height='40' src='https://name-coach.com/playbutton/7e2986bf7782324ce9d9eff538367f9736a41a43' width='40'\u003e\u003c/iframe\u003e",
      "recording_link": "https://namewaves.s3.amazonaws.com/502.mp3",
      "name_badge_link": "http://www.name-coach.com/sinduraravichandran"
    }
  ]
}

To retrieve an individual's name recording by email:

GET/?auth_token={auth_token}&access_code={access_code}&email={email}

Parameters
HideShow
auth_token
string (required) - the authentication token to access to private API 

Example: FjQB7vXvsPK_Ur6swRk7

access_code
string (required) - access code for a Name Page 

Example: example-237eyc55

email
string (optional) - individual's email 

Example:  oluwarotimi-adesina@example.com

include_extended_attributes
boolean (optional) - specify behaviour of receiving custom attribute values 

Example:  true

institution_id
string (optional) - individual's internal school id 

Example:  example123

Example (cURL) 
curl --header "Content-Type: application/json" "https://name-coach.com/api/private/v3/names?access_code=example-237eyc55&auth_token=FjQB7vXvsPK_Ur6swRk7&email=oluwarotimi-adesina@example.com"
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": "success",
  "data": [
    {
      "first_name": "Oluwarotimi",
      "last_name": "Adesina",
      "email": "oluwarotimi-adesina@example.com",
      "embed_image": "\u003cimg alt=\"Playbutton 9814faf2f7896737e991d283f48914d0177804a8cd8d605a7321abd15c0832b1\" height=\"15\" onclick=\"javascript:(function() {\n  var audio = document.createElement(\u0026#39;audio\u0026#39;);\n  audio.src = \u0026quot;https://namewaves.s3.amazonaws.com/502.mp3?digest=38506\u0026quot;;\n  audio.play();\n}).call();\n\" src=\"https://name-coach.com/images/playbutton-9814faf2f7896737e991d283f48914d0177804a8cd8d605a7321abd15c0832b1.png\" width=\"15\" /\u003e",
      "embed_iframe": "\u003ciframe frameborder='0' height='40' src='https://name-coach.com/playbutton/d9f2720effc29fa9075a4526fd5e20ea19d9e228' width='40'\u003e\u003c/iframe\u003e",
      "recording_link": "https://namewaves.s3.amazonaws.com/1980_2124_6C854.mp3",
      "name_badge_link": "http://www.name-coach.com/oluwarotimiadesina"
    }
  ]
}

To retrieve an individual's name recording by its params:

GET/?auth_token={auth_token}&email={email}&first_name={first_name}

Parameters
HideShow
auth_token
string (required) - the authentication token to access to private API 

Example: FjQB7vXvsPK_Ur6swRk7

access_code
string (required) - access code for a Name Page 

Example: example-237eyc55

email
string (optional) - individual's email 

Example:  oluwarotimi-adesina@example.com

include_extended_attributes
boolean (optional) - specify behaviour of receiving custom attribute values 

Example:  true

institution_id
string (optional) - individual's internal school id 

Example:  example123

first_name
string (optional) - individual's first name 

Example:  Oluwarotimi

last_name
string (optional) - individual's last name 

Example:  Adesina

Example (cURL) 
curl --header "Content-Type: application/json" "https://name-coach.com/api/private/v3/name?auth_token=FjQB7vXvsPK_Ur6swRk7&access_code=example-237eyc55&email=oluwarotimi-adesina@example.com&first_name=Oluwarotimi"
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": "success",
  "data": [
    {
      "first_name": "Oluwarotimi",
      "last_name": "Adesina",
      "institution_id": null,
      "event_title": "gender inclusivity example",
      "event_slug": "gender-inclusivity-example",
      "event_access_code": "7960B",
      "email": "oluwarotimi-adesina@example.com",
      "embed_image": "\u003cimg alt=\"Playbutton 9814faf2f7896737e991d283f48914d0177804a8cd8d605a7321abd15c0832b1\" height=\"15\" onclick=\"javascript:(function() {\n  var audio = document.createElement(\u0026#39;audio\u0026#39;);\n  audio.src = \u0026quot;https://namewaves.s3.amazonaws.com/502.mp3?digest=38506\u0026quot;;\n  audio.play();\n}).call();\n\" src=\"https://name-coach.com/images/playbutton-9814faf2f7896737e991d283f48914d0177804a8cd8d605a7321abd15c0832b1.png\" width=\"15\" /\u003e",
      "embed_iframe": "\u003ciframe frameborder='0' height='40' src='https://name-coach.com/playbutton/d9f2720effc29fa9075a4526fd5e20ea19d9e228' width='40'\u003e\u003c/iframe\u003e",
      "recording_link": "https://namewaves.s3.amazonaws.com/1980_2124_6C854.mp3",
      "name_badge_link": "http://www.name-coach.com/oluwarotimiadesina"
    }
  ]
}

To search participants name recordings by their emails or institution ids:

POST/?auth_token={auth_token}email_list={email_list}

Parameters
HideShow
auth_token
string (required) - the authentication token to access to private API 

Example: FjQB7vXvsPK_Ur6swRk7

email_list
string (optional) - Emails list 

Example: oluwarotimi-adesina@example.com,karla-gleichauf@example.com

institution_id_list
string (optional) - indivaduals institution id list 

Example: 111,222

Example (cURL) 
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "auth_token=FjQB7vXvsPK_Ur6swRk7&email_list=oluwarotimi-adesina@example.com,karla-gleichauf@example.com" "https://name-coach.com/api/private/v3/names/search"
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": "success",
  "data": [
      {
          "first_name": "Karla",
          "last_name": "Gleichauf",
          "email": "karla-gleichauf@example.com",
          "institution_id": "",
          "event_title": "Commencement ceremony",
          "event_slug": "commencement-ceremony-32b0ac13-eaa5-4d95-a9a7-297c2a852b59",
          "event_access_code": "407C4",
          "embed_image": null,
          "embed_iframe": "<iframe src='https://name-coach.com/playbutton/4cfdc9495c12b049b37bb9eeeb395c69' width='40' height='40' frameborder='0'></iframe>",
          "recording_link": null,
          "name_badge_link": "",
          "photo": null
      },
      {
          "first_name": "Karla",
          "last_name": "Gleichauf",
          "email": "karla-gleichauf@example.com",
          "institution_id": null,
          "event_title": "Example Api Event",
          "event_slug": "example-api-event",
          "event_access_code": "3A0CB",
          "embed_image": "<img onclick=\"javascript:(function() {\n  var audio = document.createElement('audio');\n  audio.src = "https://namewaves.s3.amazonaws.com/19.mp3?digest=38508";\n  audio.play();\n}).call();\n\" src=\"https://name-coach.com/images/playbutton-9814faf2f7896737e991d283f48914d0177804a8cd8d605a7321abd15c0832b1.png\" alt=\"Playbutton\" width=\"15\" height=\"15\" />",
          "embed_iframe": "<iframe src='https://name-coach.com/playbutton/7e2986bf7782324ce9d9eff538367f9736a41a43' width='40' height='40' frameborder='0'></iframe>",
          "recording_link": "https://namewaves.s3.amazonaws.com/19.mp3?digest=38508",
          "name_badge_link": "https://name-coach.com/karlagleichauf",
          "photo": "https://name-coach.com/assets/photo-blank-39d294fa0b968674e8083c0d028eca769b5a6d0989974c8b45d4c6cfc2eca651.gif"
      },
      {
          "first_name": "Oluwarotimi",
          "last_name": "Adesina",
          "email": "oluwarotimi-adesina@example.com",
          "institution_id": null,
          "event_title": "Example Api Event",
          "event_slug": "example-api-event",
          "event_access_code": "3A0CB",
          "embed_image": "<img onclick=\"javascript:(function() {\n  var audio = document.createElement('audio');\n  audio.src = "https://namewaves.s3.amazonaws.com/1980_2124_6C854.mp3?digest=38507";\n  audio.play();\n}).call();\n\" src=\"https://name-coach.com/images/playbutton-9814faf2f7896737e991d283f48914d0177804a8cd8d605a7321abd15c0832b1.png\" alt=\"Playbutton\" width=\"15\" height=\"15\" />",
          "embed_iframe": "<iframe src='https://name-coach.com/playbutton/14b4a292fc9034ff65bb2523412282d71e4251ce' width='40' height='40' frameborder='0'></iframe>",
          "recording_link": "https://namewaves.s3.amazonaws.com/1980_2124_6C854.mp3?digest=38507",
          "name_badge_link": "https://name-coach.com/oluwarotimiadesina",
          "photo": "https://name-coach.com/assets/photo-blank-39d294fa0b968674e8083c0d028eca769b5a6d0989974c8b45d4c6cfc2eca651.gif"
      }
  ]
}