Back to top NameCoach Integration API v4 Back to top

NameCoach Integration API v5

NameCoach API v5 Root

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

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.

Next fields only available with permissions for multiple recordings feature:

  • legal_first_name (string)

  • legal_last_name (string)

  • legal_middle_name (string)

  • legal_recording_url (string)

  • legal_phonetic (string)

  • legal_notes (string)

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

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

Participants Collection

Retrieve Participants Page
GET/participants

Example (cURL) 

curl -X GET \
     'https://www.name-coach.com/api/private/v5/participants?updated_after={updated_after}&updated_before={updated_before}' \
     -H 'accept: application/json' \
     -H 'authorization: FjQB7vXvsPK_Ur6swRk7'

Example URI

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

Ignored if filters are present

The page of participants to return

per_page
number (optional) Default: 10 Example: 10

Ignored if filters are present

The page size of participants to return

include
string (optional) Example: embeddables,custom_attributes,legal_embeddables

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

Choices: custom_attributes embeddables legal_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.

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
{
  "Response": {
    "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",
        "custom_gender_pronouns": "pronouns 1",
        "legal_first_name": "Johny 1"
      },
      {
        "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",
        "custom_gender_pronouns": "pronouns 2",
        "legal_first_name": "Johny 2"
      },
      {
        "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",
        "custom_gender_pronouns": "pronouns 3",
        "legal_first_name": "Johny 3"
      }
    ],
    "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/v5/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,legal_embeddables

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

Choices: custom_attributes embeddables legal_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
{
  "Response": {
    "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",
        "custom_gender_pronouns": "pronouns 1",
        "legal_first_name": "Johny 1"
      },
      {
        "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",
        "custom_gender_pronouns": "pronouns 2",
        "legal_first_name": "Johny 2"
      },
      {
        "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",
        "custom_gender_pronouns": "pronouns 3",
        "legal_first_name": "Johny 3"
      }
    ],
    "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/v5/participants/latest \
      -H 'accept: application/json' \
      -H 'authorization: FjQB7vXvsPK_Ur6swRk7'

Example URI

GET /participants/latest
URI Parameters
HideShow
tokens
array[String] (required) Example: [`karla-gleichauf@example.com`]

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

include
string (optional) Example: embeddables,custom_attributes,legal_embeddables

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

Choices: custom_attributes embeddables legal_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
{
  "participants": [
    {
      "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",
      "legal_first_name": "Johny"
    }
  ]
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Found"
}

Pronunciations

Participants Collection

Retrieve Pronunciations Page
POST/pronunciations/search

Example (cURL) 

curl -X POST \'https://www.name-coach.com/api/private/v5/pronunciations/search' \-H 'accept: application/json' \-H 'authorization: FjQB7vXvsPK_Ur6swRk7' \-d '{"identifiers": [{"email": "simple.mail+1@example.com","institution_id": "custom_id#1"},{"email": "simple.mail+2@example.com","institution_id": "custom_id#2"}]}'

Example URI

POST /pronunciations/search
URI Parameters
HideShow
identifiers
object (required) 

A list of emails and institution_id to return in the response.

Request
HideShow
Headers
Accept: application/json
Authorization: Authorization Token
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "Response": {
      "pronunciations": [
        {
          "first_name": "John",
          "last_name": "Snow",
          "email": "buster@example.com",
          "recording_link": null,
          "institution_id": null,
          "recorded_at": "2018-10-11T04:13:38.593-07:00"
        },
        {
          "first_name": "Alex",
          "last_name": "Eugene",
          "email": "buster_test@example.com",
          "recording_link": null,
          "institution_id": null,
          "recorded_at": "2018-10-11T04:13:38.593-07:00"
        }
      ]
}}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{"message": "Not Authorized"}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{"message": "Not Found"}

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/v5/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_ids": [0]
       }'

Example URI

POST /lti/moodle/courses/synchronize
URI Parameters
HideShow
api_token
string (required) 
external_course_ids
array (required) 
Request
HideShow
Headers
Authorization: AccessToken
Accept: application/json
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Response  202
HideShow
Headers
Content-Type: application/json
Body
{
  "external_courses_ids": [
    "0",
    "1"
  ],
  "message": "Not found in Moodle"
}
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  422
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "API integration for tool consumer is disabled"
}