Back to top NameCoach Integration API v4 Back to top

NameCoach Integration API v4

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

NameCoach API v4 Root

https://www.name-coach.com/api/private/v4

Authorization

Request Authorization

You have to provide the authorization token for the customer account that contains the Name Page. You can get this value by visiting the Account menu at the Name Coach Web site.

Example
GET/resource

Example URI

GET /resource
Request
HideShow
Headers
Authorization: Authorization Token
Response  200
HideShow
Headers
Content-Type: application/json
Body
{ ... Resource body ... }
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}

API Rate Limits

Description

Rate limiting of the API is performed per user authorization token.

Rate limits are divided into 15-minute intervals and are determined globally. All API resources share the same bucket of 1000 requests per window.

When a client exceeds the API rate limit, the request rate is throttled to a single request per second. If the client exceeds a throttling period rate limit the API will return an HTTP 429 "Too Many Requests".

Response Headers

  • Nc-Rate-Limit-Limit the rate limit ceiling

  • Nc-Rate-Limit-Remaining the number of requests left for the 15 minute window

  • Nc-Rate-Limit-Reset the remaining window before the rate limit resets, in seconds

Example
GET/resource

Example URI

GET /resource
Request
HideShow
Headers
Accept: application/json
Authorization: Authorization Token
Response  200
HideShow
Headers
Content-Type: application/json
Nc-Rate-Limit-Limit: 300
Nc-Rate-Limit-Remaining: 295
Nc-Rate-Limit-Reset: 841
Body
{ ... Resource body ... }
Response  429
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Too Many Requests"
}

Participants

This section describes the ways to retrieve participants.

A Participant object has the following attributes:

  • first_name (string)

  • last_name (string)

  • email (string)

  • recording_url (string) - The participant’s name recording URL

  • event_title (string)

  • event_access_code (string) - The Access Code you may use as an identifier

  • institution_id (string) - The participant’s internal school ID

  • photo (string) - The particiapant’s photo URL (if present)

  • name_badge_link (string) - The link to a NameBadge containing the audio name recording and other cultural information about this individual

  • custom_objects (object) - A key-value pairs of the participant’s custom attributes

    • Key: honorific (string) Field name
    • Value: Mr. (string) The participant’s value for a custom field

  • embed_image (string) An image HTML code which plays the participant’s recording when clicked.

  • embed_iframe (string) An iframe HTML code which results in player button for the participant’s recording.

Participant Resource

Retrieve Participant
GET/participants/{id_or_email}

Example (cURL) 

curl -X GET \
      https://www.name-coach.com/api/private/v4/participants/karla-gleichauf@example.com \
      -H 'accept: application/json' \
      -H 'authorization: FjQB7vXvsPK_Ur6swRk7'

Example URI

GET /participants/karla-gleichauf@example.com
URI Parameters
HideShow
id_or_email
string (required) Example: karla-gleichauf@example.com

The participant identifier. An email or token can be used.

include
string (optional) Example: embeddables,custom_attributes

A comma separated set of resources to include into the response.

Choices: custom_attributes

icon_code
number (optional) 

An icon image code for embeddable resource

Choises: 0 for Image, 1 for Image, 2 for Image

play_button_img_url
string (optional) 

An image url for embeddable resource

Request
HideShow
Headers
Accept: application/json
Authorization: Authorization Token
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "participant": {
    "first_name": "Karla",
    "last_name": "Gleichauf",
    "email": "karla-gleichauf@example.com",
    "recording_link": "https://namewaves.s3.amazonaws.com/19.mp3?digest=fc6cf60196071e6763ee7e9d9f943acc",
    "event_title": "Example Api Event",
    "event_slug": "example-api-event",
    "event_access_code": "3A0CB",
    "institution_id": null,
    "photo": "https://www.name-coach.com/images/photo-blank.gif",
    "name_badge_link": "https://www.name-coach.com/karlagleichauf"
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Found"
}
Response  429
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Too Many Requests"
}

Participants Collection

Retrieve Participants Page
GET/participants{?page}{&per_page}

Example (cURL) 

curl -X GET \
     'https://www.name-coach.com/api/private/v4/participants?page=1&per_page=3' \
     -H 'accept: application/json' \
     -H 'authorization: FjQB7vXvsPK_Ur6swRk7'

Example URI

GET /participants?page=3&per_page=10
URI Parameters
HideShow
page
number (optional) Default: 1 Example: 3

The page of participants to return

per_page
number (optional) Default: 10 Example: 10

The page size of participants to return

include
string (optional) Example: embeddables,custom_attributes

A comma separated set of resources to include into the response.

Choices: custom_attributes embeddables

email_list
string (optional) Example: elmira.kaulke@example.org,amaya@example.com

A list of emails to return in the response.

institution_id_list
string (optional) Example: 111,222,333

A list of participant institution IDs to return in the response.

icon_code
number (optional) Example: 1

An icon image code for embeddable resource

Choises: 0 for Image, 1 for Image, 2 for Image

play_button_img_url
string (optional) 

An image url for embeddable resource

Request
HideShow
Headers
Accept: application/json
Authorization: Authorization Token
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "participants": [
    {
      "first_name": "John",
      "last_name": "Snow",
      "email": "buster_test2@example.com",
      "recording_link": null,
      "event_title": "Example Api Event",
      "event_slug": "example-api-event",
      "event_access_code": "3A0CB",
      "institution_id": null,
      "photo": "https://www.name-coach.com/images/photo-blank.gif",
      "name_badge_link": "https://www.name-coach.com/john-snow-13014cd1-4d53-4995-bb83-a17bcafff9fa"
    },
    {
      "first_name": "John",
      "last_name": "Snow",
      "email": "buster_test@example.com",
      "recording_link": null,
      "event_title": "Example Api Event",
      "event_slug": "example-api-event",
      "event_access_code": "3A0CB",
      "institution_id": null,
      "photo": "https://www.name-coach.com/images/photo-blank.gif",
      "name_badge_link": "https://www.name-coach.com/john-snow-0db0906a-b437-43a4-bb20-2c01d1993641"
    },
    {
      "first_name": "John",
      "last_name": "Snow",
      "email": "buster@example.com",
      "recording_link": null,
      "event_title": "Example Api Event",
      "event_slug": "example-api-event",
      "event_access_code": "3A0CB",
      "institution_id": null,
      "photo": "https://www.name-coach.com/images/photo-blank.gif",
      "name_badge_link": "https://www.name-coach.com/john-snow"
    }
  ],
  "meta": {
    "next_page_url": "https://www.name-coach.com/api/private/v4/participants?format=json&page=2&per_page=3",
    "self_url": "https://www.name-coach.com/api/private/v4/participants?format=json&page=1&per_page=3",
    "total_count": 9,
    "total_pages": 3,
    "count": 3
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Found"
}
Response  429
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Too Many Requests"
}

Participants Large Collection

Retrieve Participants Large Page
POST/participants/search

Example (cURL) 

curl -X POST \
     'https://www.name-coach.com/api/private/v4/participants/search' \
     -H 'accept: application/json' \
     -H 'authorization: FjQB7vXvsPK_Ur6swRk7' \
     -d '{
       "page": "3",
       "per_page": "10",
       "email_list": "amaya@example.com"
     }'

Example URI

POST /participants/search
URI Parameters
HideShow
page
number (optional) Default: 1 Example: 3

The page of participants to return

per_page
number (optional) Default: 10 Example: 10

The page size of participants to return

include
string (optional) Example: embeddables,custom_attributes

A comma separated set of resources to include into the response.

Choices: custom_attributes embeddables

email_list
array[string] (required) Example: elmira.kaulke@example.org,amaya@example.com

Required if institution_id_list isn’t provided

A list of emails to return in the response.

institution_id_list
array[string] (required) Example: 111,222,333

Required if email_list isn’t provided

A list of participant institution IDs to return in the response.

updated_after
string (optional) Example: 2017-01-01T00:00:00+0000

An ISO-8601 formatted time with a time zone

updated_before
string (optional) Example: 2017-01-01T00:00:00+0000

An ISO-8601 formatted time with a time zone

icon_code
number (optional) Example: 1

An icon image code for embeddable resource

Choises: 0 for Image, 1 for Image, 2 for Image

play_button_img_url
string (optional) 

An image url for embeddable resource

Request
HideShow
Headers
Accept: application/json
Authorization: Authorization Token
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "participants": [
    {
      "first_name": "John",
      "last_name": "Snow",
      "email": "buster_test2@example.com",
      "recording_link": null,
      "event_title": "Example Api Event",
      "event_slug": "example-api-event",
      "event_access_code": "3A0CB",
      "institution_id": null,
      "photo": "https://www.name-coach.com/images/photo-blank.gif",
      "name_badge_link": "https://www.name-coach.com/john-snow-13014cd1-4d53-4995-bb83-a17bcafff9fa"
    },
    {
      "first_name": "John",
      "last_name": "Snow",
      "email": "buster_test@example.com",
      "recording_link": null,
      "event_title": "Example Api Event",
      "event_slug": "example-api-event",
      "event_access_code": "3A0CB",
      "institution_id": null,
      "photo": "https://www.name-coach.com/images/photo-blank.gif",
      "name_badge_link": "https://www.name-coach.com/john-snow-0db0906a-b437-43a4-bb20-2c01d1993641"
    },
    {
      "first_name": "John",
      "last_name": "Snow",
      "email": "buster@example.com",
      "recording_link": null,
      "event_title": "Example Api Event",
      "event_slug": "example-api-event",
      "event_access_code": "3A0CB",
      "institution_id": null,
      "photo": "https://www.name-coach.com/images/photo-blank.gif",
      "name_badge_link": "https://www.name-coach.com/john-snow"
    }
  ],
  "meta": {
    "next_page_url": "https://www.name-coach.com/api/private/v4/participants?format=json&page=2&per_page=3",
    "self_url": "https://www.name-coach.com/api/private/v4/participants?format=json&page=1&per_page=3",
    "total_count": 9,
    "total_pages": 3,
    "count": 3
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Found"
}
Response  429
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Too Many Requests"
}

User latest participant

Retrieve User Latest Participant
GET/participants/latest

Example (cURL) 

curl -X GET \
      https://www.name-coach.com/api/private/v4/participants/latest \
      -H 'accept: application/json' \
      -H 'authorization: FjQB7vXvsPK_Ur6swRk7'

Example URI

GET /participants/latest
URI Parameters
HideShow
token
string (required) Example: karla-gleichauf@example.com

The user identifier. An email or uid can be used.

include
string (optional) Example: embeddables,custom_attributes

A comma separated set of resources to include into the response.

Choices: custom_attributes

icon_code
number (optional) 

An icon image code for embeddable resource

Choises: 0 for Image, 1 for Image, 2 for Image

play_button_img_url
string (optional) 

An image url for embeddable resource

Request
HideShow
Headers
Accept: application/json
Authorization: Authorization Token
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "participant": {
    "first_name": "Karla",
    "last_name": "Gleichauf",
    "email": "karla-gleichauf@example.com",
    "recording_link": "https://namewaves.s3.amazonaws.com/19.mp3?digest=fc6cf60196071e6763ee7e9d9f943acc",
    "recording_date": "2018-10-11T04:09:04.718-07:00",
    "custom_objects_recorded_date": "2018-10-11T04:13:38.593-07:00",
    "event_title": "Example Api Event",
    "event_slug": "example-api-event",
    "event_access_code": "3A0CB",
    "institution_id": null,
    "photo": "https://www.name-coach.com/images/photo-blank.gif",
    "name_badge_link": "https://www.name-coach.com/karlagleichauf"
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Found"
}

Name Page Participants

This section describes the ways to retrieve participants in the context of a name page.

Name Page Participants Collection

Create Participant
POST/name_pages/{name_page_id}/participants

Create a NamePage participant.

A participant object has the following attributes:

  • phone_number (string) +16461111111 A user phone number

  • first_name (string) John

  • last_name (string) Snow

  • email (string) john@example.com

  • custom_objects (object) A key-value pairs of the participant’s custom attributes

    • Key custom_honorific (string) An import key of the custom field
    • Value Mr. (string)

Example (cURL) 

curl -X POST \
      https://www.name-coach.com/api/private/v4/name_pages/example-api-event/participants \
      -H 'accept: application/json' \
      -H 'authorization: FjQB7vXvsPK_Ur6swRk7' \
      -H 'content-type: application/json' \
      -d '{
      "participant": {
        "first_name": "John",
        "last_name": "Snow",
        "phone_number": "+16462234567",
        "notes": "some text",
        "email": "buster@example.com",
        "custom_objects": {
        }
      }
    }'

Example URI

POST /name_pages/example-api-event/participants
URI Parameters
HideShow
name_page_id
string (required) Example: example-api-event
Request
HideShow
Headers
Authorization: Authorization Token
Content-Type: application/json
Accept: application/json
Body
{
  "participant": {
    "first_name": "John",
    "last_name": "Snow",
    "phone_number": "+16462234567",
    "notes": "some text",
    "email": "buster@example.com",
    "custom_objects": {
      "custom_field_1": "SDM",
      "custom_field_2": "Mr"
    }
  }
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "participant": {
    "first_name": "John",
    "last_name": "Snow",
    "email": "busters@example.com",
    "recording_link": null,
    "event_title": "Example Api Event",
    "event_slug": "example-api-event",
    "event_access_code": "3A0CB",
    "institution_id": null,
    "photo": "https://www.name-coach.com/images/photo-blank.gif",
    "name_badge_link": "https://www.name-coach.com/john-snow-2ee00bf8-08f1-4455-96cb-90544ef1d188",
    "custom_objects": {}
  },
  "meta": {
    "link": "https://www.name-coach.com/api/private/v4/participants/29026497041d247980ba308931d73c15"
  }
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Unprocessable entity",
  "errors": {
    "phone_number": [
      "Is not valid."
    ],
    "email": [
      "is invalid",
      "can't be blank"
    ],
    "notes": [
      "can't be blank"
    ]
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Found"
}
Response  420
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Bad Request"
}
Response  429
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Too Many Requests"
}

Retrieve Participants Page
GET/name_pages/{name_page_id}/participants{?page}{&per_page}{&include}{&email_list}{&institution_id_list}{&icon_code}{&play_button_img_url}

Example (cURL) 

curl -X GET \
      'https://www.name-coach.com/api/private/v4/name_pages/example-api-event/participants?page=1&per_page=10&include=embeddables%2Ccustom_attributes&email_list=sindura-ravichandran%40example.com%2Coluwarotimi-adesina%40example.com%2Ckarla-gleichauf%40example.com&icon_code=0&play_button_img_url=http%3A%2Fexample.com%2Fimage.png' \
      -H 'accept: application/json' \
      -H 'authorization: FjQB7vXvsPK_Ur6swRk7' \
      -H 'content-type: application/json' \
      -d '{
      "participant": {
        "first_name": "John",
        "last_name": "Snow",
        "phone_number": "+16462234567",
        "notes": "some text",
        "email": "buster@example.com",
        "custom_objects": {
        }
      }
    }'

Example URI

GET /name_pages/example-api-event/participants?page=1&per_page=10&include=embeddables,custom_attributes&email_list=sindura-ravichandran@40example.com,oluwarotimi-adesina@40example.com,karla-gleichauf@40example.com&institution_id_list=111,222,333&icon_code=0&play_button_img_url=http:/example.com/image.png
URI Parameters
HideShow
name_page_id
string (required) Example: example-api-event

The name page identifier. An event code or slug.

page
number (optional) Default: 1 Example: 1

The page of participants to return

per_page
number (optional) Default: 10 Example: 10

The page size of participants to return

include
string (optional) Example: embeddables,custom_attributes

A comma separated set of resources to include into the response.

Choices: custom_attributes embeddables

email_list
string (optional) Example: sindura-ravichandran@40example.com,oluwarotimi-adesina@40example.com,karla-gleichauf@40example.com

A list of emails to return in the response.

institution_id_list
string (optional) Example: 111,222,333

A list of participant institution IDs to return in the response.

icon_code
number (optional) Example: 0

An icon image code for embeddable resource

Choises: 0 for Image, 1 for Image, 2 for Image

play_button_img_url
string (optional) Example: http://example.com/image.png

An image url for embeddable resource

Request
HideShow
Headers
Accept: application/json
Authorization: Authorization Token
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "participants": [
    {
      "first_name": "Karla",
      "last_name": "Gleichauf",
      "email": "karla-gleichauf@example.com",
      "recording_link": "https://namewaves.s3.amazonaws.com/19.mp3?digest=fc6cf60196071e6763ee7e9d9f943acc",
      "event_title": "Example Api Event",
      "event_slug": "example-api-event",
      "event_access_code": "3A0CB",
      "institution_id": null,
      "photo": "https://www.name-coach.com/images/photo-blank.gif",
      "name_badge_link": "https://www.name-coach.com/karlagleichauf",
      "custom_objects": {},
      "embed_image": "<span id=\"container_7e2986bf7782324ce9d9eff538367f9736a41a430\" style=\"position: relative; height: 30px; width: 30px; opacity: 1\"> <span id=\"playback_7e2986bf7782324ce9d9eff538367f9736a41a430\" style=\"\"> <img class=\"logo-sign\" src=\"https://www.name-coach.com/images/animate.gif\" width=\"20\"> </span> <img id=\"image_7e2986bf7782324ce9d9eff538367f9736a41a430\" role=\"button\" alt=\"\" src=\"http:/example.com/image.png\" width=\"20\"> <script> (function() { function playButton() { var audio = document.createElement('audio'); var playback = document.getElementById(\"playback_7e2986bf7782324ce9d9eff538367f9736a41a430\"); var image = document.getElementById(\"image_7e2986bf7782324ce9d9eff538367f9736a41a430\"); audio.src = \"https://namewaves.s3.amazonaws.com/19.mp3?digest=fc6cf60196071e6763ee7e9d9f943acc\"; function onPlayFinished() { playback.setAttribute(\"style\", \"display: none;\"); image.setAttribute(\"style\", \"display: inline-block;\"); } function onPlay() { image.setAttribute(\"style\", \"display: none;\"); playback.setAttribute(\"style\", \"display: inline-block;\"); setTimeout(onPlayFinished, audio.duration * 1000); } function onPlayClicked() { audio.play().then(onPlay); } playback.setAttribute(\"style\", \"display: none;\"); image.addEventListener('click', onPlayClicked); } var image = document.getElementById(\"image_7e2986bf7782324ce9d9eff538367f9736a41a430\"); if(image) { playButton(); } else { document.addEventListener('DOMContentLoaded', function() { playButton(); }); } }).call(); </script> </span>",
      "embed_iframe": "<iframe src=\"https://www.name-coach.com/playbutton/7e2986bf7782324ce9d9eff538367f9736a41a43\" width=\"40\" height=\"40\" frameborder=\"0\"></iframe>"
    },
    {
      "first_name": "Oluwarotimi",
      "last_name": "Adesina",
      "email": "oluwarotimi-adesina@example.com",
      "recording_link": "https://namewaves.s3.amazonaws.com/1980_2124_6C854.mp3?digest=fc6cf60196071e6763ee7e9d9f943acc",
      "event_title": "Example Api Event",
      "event_slug": "example-api-event",
      "event_access_code": "3A0CB",
      "institution_id": null,
      "photo": "https://www.name-coach.com/images/photo-blank.gif",
      "name_badge_link": "https://www.name-coach.com/oluwarotimiadesina",
      "custom_objects": {},
      "embed_image": "<span id=\"container_14b4a292fc9034ff65bb2523412282d71e4251ce0\" style=\"position: relative; height: 30px; width: 30px; opacity: 1\"> <span id=\"playback_14b4a292fc9034ff65bb2523412282d71e4251ce0\" style=\"\"> <img class=\"logo-sign\" src=\"https://www.name-coach.com/images/animate.gif\" width=\"20\"> </span> <img id=\"image_14b4a292fc9034ff65bb2523412282d71e4251ce0\" role=\"button\" alt=\"\" src=\"http:/example.com/image.png\" width=\"20\"> <script> (function() { function playButton() { var audio = document.createElement('audio'); var playback = document.getElementById(\"playback_14b4a292fc9034ff65bb2523412282d71e4251ce0\"); var image = document.getElementById(\"image_14b4a292fc9034ff65bb2523412282d71e4251ce0\"); audio.src = \"https://namewaves.s3.amazonaws.com/1980_2124_6C854.mp3?digest=fc6cf60196071e6763ee7e9d9f943acc\"; function onPlayFinished() { playback.setAttribute(\"style\", \"display: none;\"); image.setAttribute(\"style\", \"display: inline-block;\"); } function onPlay() { image.setAttribute(\"style\", \"display: none;\"); playback.setAttribute(\"style\", \"display: inline-block;\"); setTimeout(onPlayFinished, audio.duration * 1000); } function onPlayClicked() { audio.play().then(onPlay); } playback.setAttribute(\"style\", \"display: none;\"); image.addEventListener('click', onPlayClicked); } var image = document.getElementById(\"image_14b4a292fc9034ff65bb2523412282d71e4251ce0\"); if(image) { playButton(); } else { document.addEventListener('DOMContentLoaded', function() { playButton(); }); } }).call(); </script> </span>",
      "embed_iframe": "<iframe src=\"https://www.name-coach.com/playbutton/14b4a292fc9034ff65bb2523412282d71e4251ce\" width=\"40\" height=\"40\" frameborder=\"0\"></iframe>"
    },
    {
      "first_name": "Sindura",
      "last_name": "Ravichandran",
      "email": "sindura-ravichandran@example.com",
      "recording_link": "https://namewaves.s3.amazonaws.com/502.mp3?digest=fc6cf60196071e6763ee7e9d9f943acc",
      "event_title": "Example Api Event",
      "event_slug": "example-api-event",
      "event_access_code": "3A0CB",
      "institution_id": null,
      "photo": "https://namephotos.s3.amazonaws.com/uploads/user/avatar/6a8d4e67-fb07-40a7-8cec-c2a1e4fb413e.jpg",
      "name_badge_link": "https://www.name-coach.com/sinduraravichandran",
      "custom_objects": {},
      "embed_image": "<span id=\"container_d9f2720effc29fa9075a4526fd5e20ea19d9e2280\" style=\"position: relative; height: 30px; width: 30px; opacity: 1\"> <span id=\"playback_d9f2720effc29fa9075a4526fd5e20ea19d9e2280\" style=\"\"> <img class=\"logo-sign\" src=\"https://www.name-coach.com/images/animate.gif\" width=\"20\"> </span> <img id=\"image_d9f2720effc29fa9075a4526fd5e20ea19d9e2280\" role=\"button\" alt=\"\" src=\"http:/example.com/image.png\" width=\"20\"> <script> (function() { function playButton() { var audio = document.createElement('audio'); var playback = document.getElementById(\"playback_d9f2720effc29fa9075a4526fd5e20ea19d9e2280\"); var image = document.getElementById(\"image_d9f2720effc29fa9075a4526fd5e20ea19d9e2280\"); audio.src = \"https://namewaves.s3.amazonaws.com/502.mp3?digest=fc6cf60196071e6763ee7e9d9f943acc\"; function onPlayFinished() { playback.setAttribute(\"style\", \"display: none;\"); image.setAttribute(\"style\", \"display: inline-block;\"); } function onPlay() { image.setAttribute(\"style\", \"display: none;\"); playback.setAttribute(\"style\", \"display: inline-block;\"); setTimeout(onPlayFinished, audio.duration * 1000); } function onPlayClicked() { audio.play().then(onPlay); } playback.setAttribute(\"style\", \"display: none;\"); image.addEventListener('click', onPlayClicked); } var image = document.getElementById(\"image_d9f2720effc29fa9075a4526fd5e20ea19d9e2280\"); if(image) { playButton(); } else { document.addEventListener('DOMContentLoaded', function() { playButton(); }); } }).call(); </script> </span>",
      "embed_iframe": "<iframe src=\"https://www.name-coach.com/playbutton/d9f2720effc29fa9075a4526fd5e20ea19d9e228\" width=\"40\" height=\"40\" frameborder=\"0\"></iframe>"
    }
  ],
  "meta": {
    "self_url": "https://www.name-coach.com/api/private/v4/name_pages/example-api-event/participants?email_list=sindura-ravichandran%40example.com%2Coluwarotimi-adesina%40example.com%2Ckarla-gleichauf%40example.com&format=json&include=embeddables%2Ccustom_attributes&page=1&per_page=10",
    "total_count": 3,
    "total_pages": 1,
    "count": 3
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Found"
}
Response  429
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Too Many Requests"
}

Participant Resource

Retrieve Participant
GET/name_pages/{name_page_id}/participants/{id_or_email}

Example (cURL) 

curl -X GET \
      https://www.name-coach.com/api/private/v4/name_pages/example-api-event/participants/karla-gleichauf@example.com \
      -H 'accept: application/json' \
      -H 'authorization: FjQB7vXvsPK_Ur6swRk7' \
      -H 'content-type: application/json' \
      -d '{
      "participant": {
        "first_name": "John",
        "last_name": "Snow",
        "phone_number": "+16462234567",
        "notes": "some text",
        "email": "buster@example.com",
        "custom_objects": {
        }
      }
    }'

Example URI

GET /name_pages/example-api-event/participants/karla-gleichauf@example.com
URI Parameters
HideShow
name_page_id
string (required) Example: example-api-event

The NamePage identifier. Event code or slug.

id_or_email
string (required) Example: karla-gleichauf@example.com

The participant identifier. An email or token can be used.

include
string (optional) Example: embeddables,custom_attributes

A comma separated set of resources to include into the response.

Choices: custom_attributes embeddables

icon_code
number (optional) 

An icon image code for embeddable resource

Choises: 0 for Image, 1 for Image, 2 for Image

play_button_img_url
string (optional) 

An image url for embeddable resource

Request
HideShow
Headers
Accept: application/json
Authorization: Authorization Token
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "participant": {
    "first_name": "Karla",
    "last_name": "Gleichauf",
    "email": "karla-gleichauf@example.com",
    "recording_link": "https://namewaves.s3.amazonaws.com/19.mp3?digest=fc6cf60196071e6763ee7e9d9f943acc",
    "event_title": "Example Api Event",
    "event_slug": "example-api-event",
    "event_access_code": "3A0CB",
    "institution_id": null,
    "photo": "https://www.name-coach.com/images/photo-blank.gif",
    "name_badge_link": "https://www.name-coach.com/karlagleichauf"
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Found"
}
Response  429
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Too Many Requests"
}

Exports

This section describes the ways to create and retrieve the export report.

An Export object has the following attributes:

  • id (string)

  • created_after (string) - An export filter

  • updated_after (string) - An export filter

  • name_page_id (string) - An export filter

  • created_at (string) - An ISO-8601 formatted time the record was created

  • expires_at (string) - An ISO-8601 formatted report expiration time

  • state (string) - An export request state

  • report (array[Participant])

Export state can have the next values:

  • initial - an export request is created and waits in the processing queue.

  • in_progress - an export request is being processed.

  • completed - an export request is finished.

  • expired - an export request is expired.

  • failed - an error occurred during export request processing.

Create Export Resource

Create Export Request
POST/exports

Creates an Export request. At least one parameter should be specified.

Provided parameters are applied as filters.

Example (cURL) 

curl -X POST \
      https://www.name-coach.com/api/private/v4/exports \
      -H 'accept: application/json' \
      -H 'authorization: FjQB7vXvsPK_Ur6swRk7' \
      -H 'content-type: application/json' \
      -d '{
      "export": {
        "updated_after": "2017-01-01T00:00:00+0000",
        "created_after": "2017-01-01T00:00:00+0000",
        "name_page_id": "example-api-event"
      }
    }'

Example URI

POST /exports
URI Parameters
HideShow
updated_after
string (optional) Example: 2017-01-01T00:00:00+0000

An ISO-8601 formatted time with a time zone

created_after
string (optional) Example: 2017-01-01T00:00:00+0000

An ISO-8601 formatted time with a time zone

name_page_id
string (optional) Example: example-api-event
Request
HideShow
Headers
Authorization: Authorization Token
Content-Type: application/json
Accept: application/json
Body
{
  "export": {
    "updated_after": "2017-01-01T00:00:00+0000",
    "created_after": "2017-01-01T00:00:00+0000",
    "name_page_id": "example-api-event"
  }
}
Response  202
HideShow
Headers
Content-Type: application/json
Body
{
  "export": {
    "created_after": "2017-01-01T00:00:00+0000",
    "updated_after": "2017-01-01T00:00:00+0000",
    "id": "09a085cc-1400-41c4-9126-ee2518e8804e",
    "state": "initial",
    "expires_at": "2017-12-14T12:32:56+0000",
    "created_at": "2017-12-14T11:32:56+0000",
    "name_page_id": "example-237eyc55"
  },
  "meta": {
    "link": "https://www.name-coach.com/api/private/v4/exports/09a085cc-1400-41c4-9126-ee2518e8804e"
  }
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Validation error",
  "errors": {
    "name_page_id": [
      "is not found"
    ]
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Found"
}
Response  429
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Too Many Requests"
}

Export Resource

Retrieve Export request attributes
GET/exports/{id}

Example (cURL) 

curl -X GET \
      https://www.name-coach.com/api/private/v4/exports/09421a0f-273d-4454-8086-6dd459977b41 \
      -H 'accept: application/json' \
      -H 'authorization: FjQB7vXvsPK_Ur6swRk7' \
      -H 'content-type: application/json' \
      -d '{
      "export": {
        "updated_after": "2017-01-01T00:00:00+0000",
        "created_after": "2017-01-01T00:00:00+0000",
        "name_page_id": "example-api-event"
      }
    }'

Example URI

GET /exports/09421a0f-273d-4454-8086-6dd459977b41
URI Parameters
HideShow
id
string (required) Example: 09421a0f-273d-4454-8086-6dd459977b41

The export object identifier.

Request
HideShow
Headers
Accept: application/json
Authorization: Authorization Token
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "export": {
    "created_after": "2017-01-01T00:00:00+0000",
    "updated_after": "2017-01-01T00:00:00+0000",
    "id": "09421a0f-273d-4454-8086-6dd459977b41",
    "state": "completed",
    "report": [
      {
        "first_name": "John",
        "last_name": "Snow",
        "email": "buster@example.com",
        "recording_link": null,
        "event_title": "Example Api Event",
        "event_slug": "example-api-event",
        "event_access_code": "3A0CB",
        "institution_id": null,
        "photo": "https://www.name-coach.com/images/photo-blank.gif",
        "name_badge_link": "https://www.name-coach.com/john-snow"
      },
      {
        "first_name": "John",
        "last_name": "Snow",
        "email": "buster_test@example.com",
        "recording_link": null,
        "event_title": "Example Api Event",
        "event_slug": "example-api-event",
        "event_access_code": "3A0CB",
        "institution_id": null,
        "photo": "https://www.name-coach.com/images/photo-blank.gif",
        "name_badge_link": "https://www.name-coach.com/john-snow-0db0906a-b437-43a4-bb20-2c01d1993641"
      },
      {
        "first_name": "John",
        "last_name": "Snow",
        "email": "buster_test2@example.com",
        "recording_link": null,
        "event_title": "Example Api Event",
        "event_slug": "example-api-event",
        "event_access_code": "3A0CB",
        "institution_id": null,
        "photo": "https://www.name-coach.com/images/photo-blank.gif",
        "name_badge_link": "https://www.name-coach.com/john-snow-13014cd1-4d53-4995-bb83-a17bcafff9fa"
      }
    ],
    "expires_at": "2017-12-14T12:07:22+0000",
    "created_at": "2017-12-14T11:07:22+0000",
    "name_page_id": "example-237eyc55"
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Found"
}
Response  429
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Too Many Requests"
}

Exports Collection

Retrieve Exports Page
GET/exports{?page}{&per_page}

Example (cURL) 

curl -X GET \
      'https://www.name-coach.com/api/private/v4/exports?page=1&per_page=10' \
      -H 'accept: application/json' \
      -H 'authorization: FjQB7vXvsPK_Ur6swRk7' \
      -H 'content-type: application/json'

Example URI

GET /exports?page=3&per_page=10
URI Parameters
HideShow
page
number (optional) Default: 1 Example: 3

The page of participants to return

per_page
number (optional) Default: 10 Example: 10

The page size of participants to return

Request
HideShow
Headers
Accept: application/json
Authorization: Authorization Token
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "exports": [
    {
      "created_after": "2017-01-01T00:00:00+0000",
      "updated_after": "2017-01-01T00:00:00+0000",
      "id": "09421a0f-273d-4454-8086-6dd459977b41",
      "state": "completed",
      "expires_at": "2017-12-14T12:07:22+0000",
      "created_at": "2017-12-14T11:07:22+0000",
      "name_page_id": "example-237eyc55"
    },
    {
      "created_after": "2017-01-01T00:00:00+0000",
      "updated_after": "2017-01-01T00:00:00+0000",
      "id": "09a085cc-1400-41c4-9126-ee2518e8804e",
      "state": "completed",
      "expires_at": "2017-12-14T12:32:56+0000",
      "created_at": "2017-12-14T11:32:56+0000",
      "name_page_id": "example-237eyc55"
    }
  ],
  "meta": {
    "self_url": "https://www.name-coach.com/api/private/v4/exports?format=json&page=1&per_page=10",
    "total_count": 2,
    "total_pages": 1,
    "count": 2
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Found"
}
Response  429
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Too Many Requests"
}

Moodle Courses

This section describes endpoints for working with Moodle Instances.

Synchronize Moodle Course

Synchronize Moodle Course
POST/lti/moodle/courses/synchronize

Example (cURL) 

curl -X POST \
      'https://www.name-coach.com/api/private/v4/lti/moodle/courses/synchronize' \
      -H 'accept: application/json' \
      -H 'authorization: auth_token' \
      -H 'content-type: application/json' \
      -d '{
         "api_token": "tool_api_token",
         "external_course_id": 0
       }'

Example URI

POST /lti/moodle/courses/synchronize
URI Parameters
HideShow
api_token
string (required) 
external_course_id
string (required) 
Request
HideShow
Headers
Authorization: AccessToken
Accept: application/json
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Bad Request"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Tool consumer not found"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Course doesn't exist in Moodle"
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "API integration for tool consumer is disabled"
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Course is synchronizing now"
}