Apptentive API Documentation

Apptentive REST API Documentation

The Apptentive REST API allows for direct access and manipulation of data stored on Apptentive servers. In addition to being used by Apptentive clients (e.g. for iPhone and Android), the REST API is used to power the Apptentive dashboard, inbox, and survey management tools at www.apptentive.com. The REST API can be used by Apptentive customers to export their data or build custom applications powered by Apptentive.

Document Contents:

Overview
Requests & Responses
Resources
- Records
- Surveys

Requests & Responses

Base URL

All Apptentive REST APIs have the following base URL:

https://api.apptentive.com

To protect the security and privacy of Apptentive data, all REST APIs are served using HTTPS.

Request and Response Formats

The Apptentive REST APIs use JSON for both requests and responses.

Authentication

All Apptentive REST APIs are scoped to given app, and require authenticaion using that app's OAuth2 access token. You may retrieve an app's access token by logging into the Apptentive Website, selecting the app whose access token you'd like the retrieve, and then navigating to that app's settings page.

YouYou may either authenticate through the use of an Authorization header, or by setting the oauth_token parameter in your request to your access token.

Example using the authorization header

curl -H "Authorization: OAuth YOUR_API_TOKEN" https://api.apptentive.com/surveys/active

Example using the query parameter

curl https://api.apptentive.com/surveys/active?oauth_token=YOUR_API_TOKEN

Response Status Codes & Errors

When making calls to the Apptentive REST API, one of the following response status code will be returned:

200 OK: The request was successful and the response body, when present, contains the updated resource.
201 CREATED: The request was successful and the provided resource has been created on the server.
304 NOT MODIFIED: The resource has not been modified on the server and your client's cached version is still up to date.
401 UNAUTHORIZED: The provided API token is either incorrect or does not have permission to access/update the requested resource.
404 NOT FOUND: The resource you're trying to access does not exist.
405 METHOD NOT ALLOWED: The resource you're accessing does not support the requested method (e.g. PUT, POST).
422 UNPROCESSABLE ENTITY: The resource you're providing to the server is incomplete and cannot be stored. The response body will typically contain the specific error that occurred.
500 SERVER ERROR: An temporary internal error has occurred. We are informed of these errors and investigate immediately. Please try your request again later.

Resources

Records

Operations

Listing
Retrieval
Creation
Archive State

Listing

Description:
Returns a listing of all records for a given app.

Method: GET

URI: /records/

Parameters:

None

Response:

An array of Apptentive records.

Example:

curl -i -H "Authorization: OAuth API_ACCESS_TOKEN" https://api.apptentive.com/records

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge
ETag: "d17f2f5c106670fb2fdc8c12ad6e2bbe"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 8d39cfcdd8db3f73c4aea197bd199ef4
X-Runtime: 1.251586
Connection: close

[
    {
        "id": "4f6cd30ba902916768000001",
        "summary": "I have a question. from Fake User",
        "device": {
            "_id": "4f6cd30fa902916768000002",
            "board": null,
            "bootloader_version": null,
            "brand": null,
            "build_id": null,
            "build_type": null,
            "carrier": null,
            "cpu": null,
            "current_carrier": null,
            "device": null,
            "manufacturer": null,
            "model": "iPhone Simulator",
            "network_type": null,
            "os_build": null,
            "os_name": null,
            "os_version": null,
            "product": null,
            "radio_version": null,
            "uuid": "46D40D5E-C11C-6F51-BD1F-CD8C922CCA1E"
        },
        "user": {
            "_id": "4f6cd313a902916768000003",
            "birthday": null,
            "city": null,
            "country": null,
            "email": "[email protected]",
            "name": "Fake User",
            "phone_number": "",
            "state": null,
            "street": null,
            "zip": null
        },
        "feedback": {
            "_id": "4f6cd318a902916768000004",
            "feedback": "I have a question",
            "source": null,
            "type": "bug"
        },
        "date": "Wed, 23 Mar 2011 04:55:00 GMT",
        "archived": true
    }
, ...
]

Retrieval

Description:
Returns a specific record for a given app.

Method: GET

URI: /records/{id}

Parameters:

id: The ID of the record to be retrieved

Response:

The requested Apptentive record.

Example:

curl -i -H "Authorization: OAuth API_ACCESS_TOKEN" https://api.apptentive.com/records/4f6cd30ba902916768000001

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge
ETag: "f14541cfa75b8d4cdd6c2396d50ef705"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 4dc7e82c3a6fcb04cacde605318a8782
X-Runtime: 0.030816
Connection: close

{
    "id": "4f6cd30ba902916768000001",
    "summary": "I have a question. from Fake User",
    "device": {
        "_id": "4f6cd30fa902916768000002",
        "board": null,
        "bootloader_version": null,
        "brand": null,
        "build_id": null,
        "build_type": null,
        "carrier": null,
        "cpu": null,
        "current_carrier": null,
        "device": null,
        "manufacturer": null,
        "model": "iPhone Simulator",
        "network_type": null,
        "os_build": null,
        "os_name": null,
        "os_version": null,
        "product": null,
        "radio_version": null,
        "uuid": "46D40D5E-C11C-6F51-BD1F-CD8C922CCA1E"
    },
    "user": {
        "_id": "4f6cd313a902916768000003",
        "birthday": null,
        "city": null,
        "country": null,
        "email": "[email protected]",
        "name": "Fake User",
        "phone_number": "",
        "state": null,
        "street": null,
        "zip": null
    },
    "feedback": {
        "_id": "4f6cd318a902916768000004",
        "feedback": "I have a question",
        "source": null,
        "type": "bug"
    },
    "date": "Wed, 23 Mar 2011 04:55:00 GMT",
    "archived": true
}

Creation

Description:
Creates an Apptentive Record

Method POST

URI: /records

Parameters:

data May be set to a JSON object containing app-specific data to be associated with the record.
file May be set to a JSON object containing key value pairs of files to associate with the record. Keys should be set to the file reference (e.g. "screenshot", "crash_log") and the value should contain the base64 encoded file.
date The date and time that the record was created on the client, which may be different that the time that the record was actually posted to the server. Should be sent in %m/%d/%Y %I:%M%p%z format to be available for filters and queries on the site.
feedback A JSON object used for creating feedback that will appear in the app inbox. The following keys are supported:
- feedback The actual feedback itself as plain text.
- type May be used to categorize the type of user provided feedback as a string. (Example: "bug", "suggestion", etc.).
user A JSON object used to store information about the user associated with this record. The following keys are supported:
- name The user's name
- email The user's email address. No validation is performed on the submitted email to ensure that it is a valid email address.
- phone_number The user's phone number. The phone number will be stored as a string without any validation on the format of the phone number. May be used to store the name of the user associated with this record.
- street The user's street address
- city The user's city
- state The user's state
- zip_code The user's zip code
- country The user's country
- zip_code The user's zip code
- birthday The user's birthday. If sent in %m/%d/%Y format, this value will be available to filters and queries on the site. If not sent in this format the birthday will be saved as a string.
device A JSON object used to store information about the device associated with this record. The following keys are supported, and all associated values are stored as a string:
- os_name The name of the OS (e.g. iOS, Android)
- os_version The build of the OS.
- os_build The version of the OS.
- manufacturer The device manufacturer.
- model The device model
- board The device board name
- product The device product name
- brand The device brand name
- cpu The device CPU type
- uuid The unique identifier of the device
- carrier The (default) carrier device
- current_carrier The device's currently active carrier
- network_type The type of cellular network that the device is currently using
- build_type The type of the device build (e.g. production, test)
- build_id The device build identifier
- bootloader_version The device bootloader version
- radio_version The device radio firmware version
client A JSON object used to store information about the Apptentive client creating this record. The following keys are supported:
- version The version of the client
- language The programming language that the client is implemented in
- author The name and/or email address of the author of the client
- platform The name or type of the platform that the client is currently running on.
app_version A JSON object used to store information about the application creating this record. The following keys are supported:
- version The application's version (treated as a string)
- build_number The build number of the application (treated as a string)
- primary_locale The primary/preferred locale for the application (e.g. "en")
- supported_locales An array of supported locales for the application (e.g. ["en", "es"])

Response:

The id of the created Apptentive record.

Example:

curl -i -X POST -H "Content-type: application/json" -H "Authorization: OAuth API_ACCESS_TOKEN"  -d '{"data": {"my_app_id": 123}, "feedback": {"feedback": "Great app!", "type": "praise"}, "user": {"name": "Sample User", "email": "[email protected]"}, "device": {"os_name": "iOS", "os_version": "5.0.1"}, "client": {"language": "curl"}}' https://api.apptentive.com/records

HTTP/1.1 201 Created
Location: https://api.apptentive.com/records/4f6cdc75a902915fa80002f3
Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge
ETag: "1249aacfe8e119402506f2ca71cfc48d"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 387218fb14b274c4691b4c466bd2c8ad
X-Runtime: 0.256560
Connection: close

{
    "id": "4f6cdc75a902915fa80002f3",
    "summary": "Great app! from Sample User",
    "device": {
        "_id": "4f6cdc75a902915fa80002f4",
        "board": null,
        "bootloader_version": null,
        "brand": null,
        "build_id": null,
        "build_type": null,
        "carrier": null,
        "cpu": null,
        "current_carrier": null,
        "device": null,
        "manufacturer": null,
        "model": null,
        "network_type": null,
        "os_build": null,
        "os_name": "iOS",
        "os_version": "5.0.1",
        "product": null,
        "radio_version": null,
        "uuid": null
    },
    "user": {
        "_id": "4f6cdc75a902915fa80002f5",
        "birthday": null,
        "city": null,
        "country": null,
        "email": "[email protected]",
        "name": "Sample User",
        "phone_number": null,
        "state": null,
        "street": null,
        "zip": null
    },
    "feedback": {
        "_id": "4f6cdc75a902915fa80002f6",
        "feedback": "Great app!",
        "source": null,
        "type": "praise"
    },
    "date": "Fri, 23 Mar 2012 20:26:29 GMT",
    "data": {
        "my_app_id": 123
    },
    "archived": false
}

Archive / Un-Archive

Description:
Toggles the archived state of a given record

Method PUT

URI: /records/{id}/toggle_archive

Parameters:

id: The ID of the record to toggle state for

Response:

Status code 204, no body.

Example:

curl -i -X PUT -H "Authorization: OAuth API_ACCESS_TOKEN" https://api.apptentive.com/records/4f6cdc75a902915fa80002f3/toggle_archive

HTTP/1.1 204 No Content
X-UA-Compatible: IE=Edge
Cache-Control: no-cache
X-Request-Id: 63ac08bc30016c7da4188448c265cbdc
X-Runtime: 0.023623
Connection: close

Surveys

Operations

Survey Structure
Listing
Retrieval
Deactivating

Survey Structure

Each survey response may contain the following fields:

id The unique id of the survey (used when submitting responses)
name The name of the survey
description A short (1-2 sentence) description of the survey.
active A boolean indicating whether the given survey is active (still accepting submissions)
date The survey creation date
success_message A message that should be shown to the user on successful submission of a survey response.
required A boolean indicating whether or not the user should be required to complete the given survey (DEPRECATED)
multiple_responses When true, indicates that the user may complete the survey more than once. When false, the survey may only be completed once by a given user.
questions An array of questions in the survey. Questions may have the following fields:
- id The id of the question
- value The question string (example: What is your favorite color?)
- type The question type. Currently one of singleline, multichoice, or multiselect.
- answer_choice An array of answer choices (only present for multichoice or multiselect surveys. The answer_choice objects have the following fields:
  - id The id of the answer choice
  - value The value/string for the choice

Listing

Description:
Retrieves the list of all surveys (optionally matching as set of criteria) for the app.

Method GET

URI: /surveys

Parameters:

All parameters are optional.

tags An array or comma separate string of tags. Only surveys matching tagged with all of the provided tags will be returned.
active 1 to only return active (non-archived) surveys. (All other values are ignored).
inactive 1 to only return inactive (archived) surveys. (All other values are ignored).
limit The maximum number of surveys to return.

Response:

An array of surveys (matching the specified parameters if provided).

Results should be considered valid for the duration set in the Cache-Control header (in seconds), and should not be cached publicly.

Example:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge
ETag: "f45b4a64930e73973e5f5e6b2348b23c"
Cache-Control: max-age=86400, private
X-Request-Id: 429c9354818d59df130442278a0610d6
X-Runtime: 0.292133
Connection: close

{
    "surveys": [
        {
            "id": "4f6362326338d40001000212",
            "questions": [
                {
                    "id": "4f6362326338d40001000213",
                    "answer_choices": [
                        {
                            "id": "4f6362326338d40001000214",
                            "value": "Answer 1"
                        },
                        {
                            "id": "4f6362326338d40001000215",
                            "value": "Answer 2"
                        },
                        {
                            "id": "4f6362326338d40001000216",
                            "value": "Answer 3"
                        }
                    ],
                    "instructions": "select one",
                    "value": "First Question",
                    "type": "multichoice",
                    "required": false
                },
                {
                    "id": "4f6362326338d40001000217",
                    "answer_choices": [
                        {
                            "id": "4f6362326338d40001000218",
                            "value": "BMW"
                        },
                        {
                            "id": "4f6362326338d40001000219",
                            "value": "Aston Martin"
                        },
                        {
                            "id": "4f6362326338d4000100021a",
                            "value": "Land Rover"
                        },
                        {
                            "id": "4f6362326338d4000100021b",
                            "value": "Tesla"
                        },
                        {
                            "id": "4f6362326338d4000100021c",
                            "value": "Other"
                        }
                    ],
                    "instructions": "select one",
                    "value": "What kind of car would you really, really like to have if given the choice?",
                    "type": "multichoice",
                    "required": false
                },
                {
                    "id": "4f6362326338d4000100021d",
                    "value": "If Other, Please Specify",
                    "type": "singleline",
                    "required": false
                }
            ],
            "date": "2012-03-16T08:54:26-07:00",
            "success_message": false,
            "name": "Test Survey",
            "description": "A survey description.",
            "required": false,
            "multiple_responses": true,
            "show_success_message": false,
            "active": false
        },
        …
    ]
}

Retrieval

Description:
Retrieves a specific survey.

Method GET

URI: /surveys/{id}

Parameters:

id: The ID of the survey to be retrieved

Response:

The requested Apptentive survey.

Example:

curl -i -H "Authorization: OAuth API_ACCESS_TOKEN" https://api.apptentive.com/surveys/4f5fdb6c1e0535635600101d

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-UA-Compatible: IE=Edge
ETag: "2b2b1a55dc1aab1c24937f4c1f6cf466"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: fb5aacefe168e1a91cec73870ebf8390
X-Runtime: 0.030032
Connection: close

{
   "id": "4f5fdb6c1e0535635600101d",
   "questions": [
       {
           "id": "4f5fdb6c1e0535635600101e",
           "answer_choices": [
               {
                   "id": "4f5fdb6c1e0535635600101f",
                   "value": "Chocolate"
               },
               {
                   "id": "4f5fdb6c1e05356356001020",
                   "value": "Vanilla"
               }
           ],
           "value": "Favorite Flavor of Ice Cream?",
           "type": "multichoice",
           "required": false
       }
   ],
   "date": "2012-03-13T16:42:36-07:00",
   "response_count": 2,
   "responses": [
       {
           "question": "Favorite Flavor of Ice Cream?",
           "type": "multichoice",
           "required": false,
           "responses": [
               {
                   "choice": "Chocolate",
                   "count": 1
               },
               {
                   "choice": "Vanilla",
                   "count": 1
               }
           ]
       }
   ],
   "success_message": false,
   "name": "Ice Cream Survey",
   "required": false,
   "multiple_responses": true,
   "show_success_message": false,
   "active": false
}

Deactivate

Description:
Deactivates the given survey

Method PUT

URI: /surveys/{id}

Parameters:

id: The id of the survey to deactivate

Response:

Status code 204, no body.

Example:

curl -i -X PUT -H "Authorization: OAuth API_ACCESS_TOKEN" https://api.apptentive.com/surveys/4f5fdb6c1e0535635600101d/deactivate

HTTP/1.1 204 No Content
X-UA-Compatible: IE=Edge
Cache-Control: no-cache
X-Request-Id: d99a277e3caf44cde97921a5af269d8f
X-Runtime: 0.031789
Connection: close

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Apptentive API Documentation

Apptentive REST API Documentation

Document Contents:

Requests & Responses

Base URL

Request and Response Formats

Authentication

Response Status Codes & Errors

Resources

Records

Listing

Retrieval

Creation

Archive / Un-Archive

Surveys

Survey Structure

Listing

Retrieval

Deactivate

Clone this wiki locally