Back to top NameCoach Integration API v5 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.

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
int (optional) Default: 1 Example: 3

Ignored if filters are present

The page of participants to return

per_page
int (optional) Default: 10 Example: 10

Ignored if filters are present

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.

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
int (optional) Example: 1

An icon image code for embeddable resource

Choises: 0 for Image, 1 for Image, 3 for Image

play_button_img_url
string (optional) 

An image url for embeddable resource

Request
HideShow
Headers
Authorization: Namecoach Access Token
Accept: application/json
Content-Type: application/json
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,
        "recording_id": 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,
        "recording_id": 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,
        "recording_id": 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
int (optional) Default: 1 Example: 3

The page of participants to return

per_page
int (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 (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
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
int (optional) Example: 1

An icon image code for embeddable resource

Choises: 0 for Image, 1 for Image, 3 for Image

play_button_img_url
string (optional) 

An image url for embeddable resource

Request
HideShow
Headers
Authorization: Namecoach Access Token
Accept: application/json
Content-Type: application/json
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,
        "recording_id": 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,
        "recording_id": 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,
        "recording_id": 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
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: embeddables custom_attributes

icon_code
int (optional) 

An icon image code for embeddable resource

Choises: 0 for Image, 1 for Image, 3 for Image

play_button_img_url
string (optional) 

An image url for embeddable resource

Request
HideShow
Headers
Authorization: Namecoach Access Token
Accept: application/json
Content-Type: application/json
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_id": "19",
      "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"
}

Participants Collection

Create participant
POST/participants

Create a name page participant.

A participant object has the following attributes:

  • first_name (string) John

  • last_name (string) Snow

  • notes (string) Winter is coming

  • phonetic (string) John Snow

  • email (string) john.snow@example.com

  • institution_id (string) john.snow A uniq student identifier. Can’t be changed

  • phone_number (string) +16461111111 A user phone number. Schedules a phone call if pronunciation attribute is blank

  • custom_fields (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)

  • pronunciation (object)

    • base64_str (string) Base64 encoded audio, without data format prefixes - data:audio/mp3;base64,YOUR_BASE64_STRING_HERE

  • avatar (object)

    • base64_str (string) Base64 encoded image, without data format prefixes - data:image/png;base64,YOUR_BASE64_STRING_HERE

Example (cURL) 

curl --location 'https://www.name-coach.com/api/private/v5/participants' \
        --header 'Accept: application/json' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: ••••••' \
        --data-raw '{
            "name_page_id": "event-identifier",
            "participant": {
                "email": "john.snow@example.com",
                "first_name": "John",
                "last_name": "Snow",
                "phone_number": "+16462234567",
                "notes": "Some notes",
                "phonetic": "Some phonetic",
                "avatar": {
                    "base64_set": "base64_encoded_image"
                },
                "pronunciation": {
                    "base64_set": "base64_encoded_audio"
                },
                "custom_fields": {
                    "pronounce": "Custom pronounce"
                }
            }
        }'

Example URI

POST /participants
URI Parameters
HideShow
name_page_id
string (required) 
Request
HideShow
Headers
Authorization: Namecoach Access Token
Accept: application/json
Content-Type: application/json
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "participant": {
    "first_name": "John",
    "last_name": "Snow",
    "email": "john.snow@example.com",
    "recording_link": null,
    "recording_id": null,
    "event_title": "Example Api Event",
    "event_slug": "example-api-event",
    "event_access_code": "3A0CB",
    "event_code": "0882F4",
    "institution_id": null,
    "photo": "https://www.name-coach.com/images/photo-blank.gif",
    "name_badge_link": "https://www.name-coach.com/images/john-snow",
    "phonetic_spelling": "Some notes",
    "notes": "Some phonetic"
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Name page not found"
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Unprocessable entity",
  "errors": {
    "first_name": [
      "can't be blank"
    ]
  }
}
Response  429
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Too Many Requests"
}

Participants Collection

Update participant
PUT/participants/{user_email}

Update an existing name page participant.

A participant object has the following attributes:

  • first_name (string) John

  • last_name (string) Snow

  • notes (string) Winter is coming

  • phonetic (string) John Snow

  • phone_number (string) +16461111111 A user phone number. Schedules a phone call if pronunciation attribute is blank

  • custom_fields (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)

  • pronunciation (object)

    • base64_str (string) Base64 encoded audio, without data format prefixes - data:audio/mp3;base64,YOUR_BASE64_STRING_HERE

  • avatar (object)

    • base64_str (string) Base64 encoded image, without data format prefixes - data:image/png;base64,YOUR_BASE64_STRING_HERE

Example (cURL) 

curl --location 'https://www.name-coach.com/api/private/v5/participants' \
        --header 'Accept: application/json' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: ••••••' \
        --data-raw '{
            "name_page_id": "example-api-event",
            "participant": {
                "first_name": "John",
                "last_name": "Snow",
                "phone_number": "+16462234567",
                "notes": "Some notes",
                "phonetic": "Some phonetic",
                "avatar": {
                    "base64_set": "base64_encoded_image"
                },
                "pronunciation": {
                    "base64_set": "base64_encoded_audio"
                },
                "custom_fields": {
                    "pronounce": "Custom pronounce"
                }
            }
        }'

Example URI

PUT /participants/user_email
URI Parameters
HideShow
name_page_id
string (required) 
user_email
string (required) 
Request
HideShow
Headers
Authorization: Namecoach Access Token
Accept: application/json
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "participant": {
    "first_name": "John",
    "last_name": "Snow",
    "email": "john.snow@example.com",
    "recording_link": null,
    "recording_id": null,
    "event_title": "Example Api Event",
    "event_slug": "example-api-event",
    "event_access_code": "3A0CB",
    "event_code": "0882F4",
    "institution_id": null,
    "photo": "https://www.name-coach.com/images/photo-blank.gif",
    "name_badge_link": "https://www.name-coach.com/images/john-snow",
    "phonetic_spelling": "Some notes",
    "notes": "Some phonetic"
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Name page not found"
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Unprocessable entity",
  "errors": {
    "first_name": [
      "can't be blank"
    ]
  }
}
Response  429
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Too Many Requests"
}

Participants Collection

Delete participant
DELETE/participants/{user_email}

Delete an existing participant from name page.

Example (cURL) 

curl --location --request DELETE 'https://www.name-coach.com/api/private/v5/participants/john.snow@example.com' \
        --header 'Accept: application/json' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: ••••••' \
        --data '{
            "name_page_id": "example-api-event"
        }'

Example URI

DELETE /participants/user_email
URI Parameters
HideShow
name_page_id
string (required) 
user_email
string (required) 
Request
HideShow
Headers
Authorization: Namecoach Access Token
Accept: application/json
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
No content
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Registered participant not found"
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{ "message": ""Participant has pending calls"", "errors": { "first_name": ["Participant has pending calls"] } }
Response  429
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Too Many Requests"
}

Participants Collection

Delete participant's recording
DELETE/participants/{user_email}/pronunciations/

Delete an existing participant’s recording.

Example (cURL) 

curl --location --request DELETE 'https://www.name-coach.com/api/private/v5/participants/john.snow@example.com/pronunciations/recording_6684ffd47c84ef13bf0364d5cafc86ef' \
        --header 'Accept: application/json' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: ••••••'

Example URI

DELETE /participants/user_email/pronunciations/
URI Parameters
HideShow
recording_id: (string, required) - recording identifier. Can be found in API responses as `recording_id` attribute
string (required) 
user_email
string (required) 
Request
HideShow
Headers
Authorization: Namecoach Access Token
Accept: application/json
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
No content
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not Authorized"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Registered participant 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/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
int (required) 
Request
HideShow
Headers
Authorization: Namecoach Access Token
Accept: application/json
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
No content
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"
}