saygent API documentation

We have a new API!

API v1 is still available, but we really recommend that you upgrade to v2. Not all of the functionality from v1 is available yet, but there is a lot that v1 doesn't have. Check it out!

API Base URL

https://www.saygent.com/api/v1

All API calls currently point to the above url for the first version of our API.

Authentication

auth_token=[YOUR TOKEN]

We will provide you with a private auth_token which is required for every API request.

JSON Response

We send a JSON response back for every request with at least a status message.

{ "status":"success" }

{ "status":"failure", "messages":{ "auth_token": "Authentication failed" } }

Rate Limit

Each auth_token has a limit of 200 requests per hour. If you require additional requests please send an email to api@saygent.com with your company name and requirements. We will do our best to accommodate your personal needs.

https://www.saygent.com/api/v1/respondents

• Params

• auth_token
  required

  Secret token to authenticate API request.
  Example value: abcdef

• survey_id
  required

  Id of survey to add respondents to.
  Example value: 1234

respondents array

phone
required

The phone number of the respondent.
Example value: 111-111-1111

first_name
optional

First name of the respondent.
Example value: John

last_name
optional

Last name of the respondent.
Example value: Smith

email
optional

Email of the respondent.
Example value: john_smith@email.com

contact

by
optional

This can be used to immediately notify the respondent to take the survey.
Example values: call (more on the way)

{
  "auth_token":"abcdef"
  "survey_id":1234,
  "respondents":[
    {
      "phone":"111-111-1111",
      "first_name":"john",
      "last_name":"smith",
      "email":"johnsmith@example.com",
      "contact":{
        "by":"phone"
      }
    },
    {
      "phone":"222-222-2222,
      "email":"asdf.com"
    }
  ]
}
			

{
  "status": "warning",
  "respondents": [
    {
      "id": 1,
      "phone": "111-111-1111",
      "first_name": "john",
      "last_name": "smith",
      "email": "johnsmith@example.com",
      "status": "created"
    },
    {
      "phone": "222-222-2222",
      "email": "asdf.com",
      "status": "failed",
      "messages": {
        "email": "Email not in a valid format"
      }
    }
  ]
}
			

https://www.saygent.com/api/v1/respondents

• Params

• auth_token
  required

  Secret token to authenticate API request.
  Example value: abcdef

• survey_id
  required

  Id of survey to add respondents to.
  Example value: 1234

• respondent_ids
  optional

  Comma separated list of respondent ids.
  Example value: 1,2,3,4

{
  "auth_token": "asdfjkl",
  "respondent_ids": "1,2",
  "survey_id": "xyz123"
}
			

{
  "status": "success",
  "respondents": [
    {
      "id": 1,
      "phone":"111-111-1111",
      "first_name":"john",
      "last_name":"smith",
      "email":"johnsmith@example.com"
    },
    {
      "id": 2,
      "phone": 555-555-5555,
      "email": "professor@planex.com"
    }
  ]
}
			

https://www.saygent.com/api/v1/call

• Params

• auth_token
  required

  Secret token to authenticate API request.
  Example value: abcdef

• respondent_ids
  required

  Array of respondent ids.
  Example value: [1,2,3,4]

{
  "auth_token": "asbcdwwogw",
  "respondent_ids": [
    1, 2, 3
  ]
}
			

{
  "status": "warning",
  "respondents": [
    {
      "id": 1,
      "status": "queued"
    },
    {
      "id": 2,
      "status": "invalid",
      "messages": {
        "id": "Respondent id invalid"
      }
    },
    {
      "id": 3,
      "status": "queued"
    }
  ]
}
			

https://www.saygent.com/api/v1/status

• Params

• auth_token
  required

  Secret token to authenticate API request.
  Example value: abcdef

• respondent_ids
  required

  Comma separated list of respondent ids.
  Example value: 1,2,3,4

  {
    "auth_token": "asdwodj",
    "respondent_ids": "1,2,3,4"
  }
  			

  {
    "status": "warning",
    "respondents": [
      {
        "id": 1,
        "status": "called"
      },
      {
        "id": 2,
        "status": "surveyed",
      },
      {
        "id": 3,
        "status": "analyzed"
      },
      {
        "id": 4,
        "status": "invalid",
        "messages": {
        "phone": "Phone number is invalid"
      }				
    ]
  }