Introduction

Welcome to the Wootric API documentation!

You can use our API to access and update your end users, responses and declines.

All responses from the API (including errors) are in JSON. All code examples are in cURL.

Environments

Currently, Wootric supports three main environments: the EU, AU and US.

All examples provided in this section are for the US environment only. If you want to run these examples on the EU or AU environment, you need to replace the .com domain with .eu or .au.

To determine if your account runs on the EU or AU environment now, check if your account token begins with NPS-EU or NPS-AU.

Authentication

curl -i https://api.wootric.com/oauth/token \
     -F grant_type=password \
     -F username=<youremailaddress> \
     -F password=<yourpassword>

curl -i https://api.wootric.com/oauth/token?account_token=NPS-XXXX \
     -F grant_type=password \
     -F username=<youremailaddress> \
     -F password=<yourpassword>

{
  "access_token":"<youraccesstoken>",
  "token_type":"bearer",
  "expires_in":7200,
  "refresh_token":"<yourrefreshtoken>",
  "scope":"public"
}

curl -i https://api.wootric.com/oauth/token \
     -F grant_type=refresh_token \
     -F refresh_token="<yourrefreshtoken>"

{
  "access_token":"<yournewaccesstoken>",
  "token_type":"bearer",
  "expires_in":7200,
  "refresh_token":"<yournewrefreshtoken>",
  "scope":"public"
}

curl -X POST https://api.wootric.com/oauth/token \
     -F grant_type=client_credentials \
     -F client_id=<yourclientid> \
     -F client_secret=<yourclientsecret>

{
  "access_token":"<youraccesstoken>",
  "token_type":"bearer",
  "expires_in":7200,
  "scope":"public"
}

Access tokens can be retrieved using either grant_type of password with your account email and password, or grant_type of client_credentials with your application client_id and client_secret.

Wootric expects the token to be included in all API requests regardless of grant_type of password or client_credentials. We recommend to send your token as HTTP Authorization Header, for example

curl -H "Authorization: Bearer <youraccesstoken>" https://api.wootric.com/v1/end_users

Access tokens expire 2 hours after creation. New access_token can be obtained using refresh tokens as detailed in the cURL example to the right.

You must replace myaccesstoken with your personal Access Token.

Limits

$ curl -I -s -H "Authorization: Bearer <youraccesstoken>" -X GET "https://api.wootric.com/v1/end_users"
HTTP/1.1 200 OK
X-Rate-Limit-Limit: 100
X-Rate-Limit-Remaining: 97
X-Rate-Limit-Reset: 1537971859

We recently introduced usage limits to some of our API endpoints, which only allow for a certain number of requests within a minute. When that limit is reached, the API starts responding with HTTP status 429 and the client is only allowed to continue querying the API after a minute has passed. To find out if the endpoints you’re using are affected by these limits and how many requests you’re allowed to perform within a minute, check the X-Rate-Limit-* headers included in each API response (see below). If you can’t find these headers it means that the endpoint is not limited.

Header	Description
X-Rate-Limit-Limit	The maximum number of requests that the client can perform on this account within a minute.
X-Rate-Limit-Remaining	The number of remaining requests.
X-Rate-Limit-Reset	A timestamp indicating when the counter will be reset.

End Users

End User Object

A end user object has the following fields:

Attribute	Type	Description
id	integer	The ID of end user
created_at	datetime	Datetime representation of when the end user was created
updated_at	datetime	Datetime representation of when the end user was last updated
email	string	End user email
last_surveyed	datetime	Datetime representation of when the end user was last surveyed
external_created_at	integer	UNIX timestamp of when the end user was created externally
last_seen_at	datetime	Datetime representation of when the end user was last seen
properties	hash	Properties (i.e. plan, product)
phone_number	string	End user phone number
external_id	string	An optional unique string identifier
last_response	hash	The last response of the end user
settings	hash	The end user’s settings (i.e. email_nps, mobile_nps)

Last Response

The last_response hash has the following fields:

Attribute	Type	Description
id	string	The ID of response
score	integer	The response’s score
text	string	The response’s comment
survey	hash	The survey object data

Survey

The survey hash has the following field:

Attribute	Type	Description
channel	string	The channel of the survey

Get All End Users

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users"

[
  {
    "id": 1,
    "created_at" : "2014-12-01 18:36:59",
    "updated_at" : "2014-12-01 18:36:59",
    "email": "nps@example.com",
    "last_surveyed": null,
    "external_created_at": null,
    "properties": {
      "plan": "Small Business",
      "product": "Example"
    },
    "phone_number": null,
    "external_id": null,
    "last_response": null,
    "settings": {
      "email_nps": true,
      "mobile_nps": true,
      "web_nps": true,
      "force_mobile_survey": null,
      "force_web_survey": null,
      "surveys_disabled_by_end_user": null
    }
  },
  {
    "id": 2,
    "created_at": "2018-01-02 23:03:41 -0800",
    "updated_at": "2018-01-16 23:07:03 -0800",
    "email": "nps2@example.com",
    "last_surveyed": "2018-01-07 15:30:44 -0800",
    "external_created_at": 1515940485,
    "last_seen_at": null,
    "properties": {
      "country": "UK",
      "persona": "Individual",
      "pricing_plan": "Lite",
      "product_plan": "Mobile",
      "purchase_date": 1494569021,
      "revenue_amount": 10000
    },
    "phone_number": null,
    "external_id": "e9a12f9aa245cfd5",
    "last_response": {
      "id": 505550023,
      "score": 9,
      "text": "It's a great service.",
      "survey": {
        "channel": "mobile:ios"
      }
    },
    "settings": {
      "email_nps": true,
      "mobile_nps": true,
      "web_nps": true,
      "force_mobile_survey": null,
      "force_web_survey": null,
      "surveys_disabled_by_end_user": null
    }
  }
]

This endpoint retrieves all end users.

HTTP Request

GET https://api.wootric.com/v1/end_users

Scope Parameters

Scope parameters filter your end users and can also be chained together by passing multiple scope parameters in an array.

Parameter	Type	Default	Description
page (optional)	integer	1	Number of returned page, max 30
per_page (optional)	integer	25	Number of records returned on each page, max 50
created (optional)	hash	{}	Filter your end users by time of creation (UNIX timestamp type) - eq, lt, lte, gt, gte (`created[gt]=UNIX_TIMESTAMP&created[lt]=UNIX_TIMESTAMP`)
updated (optional)	hash	{}	Filter your end users by update time (UNIX timestamp type) - eq, lt, lte, gt, gte (`updated[gt]=UNIX_TIMESTAMP&updated[lt]=UNIX_TIMESTAMP`)
email (optional)	string	None	Filter end users by email (will return an array containing a single end user object if the end user with provided email exists)
sort_order (optional)	string	asc	Order in which records are shown. Default is oldest first. Options are `asc` or `desc`
sort_key (optional)	string	email	Sort your results based on this attribute. Default is end_user’s `email`. It could be one of `email`, `updated_at`, `created_at`.
surveys_disabled (optional)	boolean	false	Filter your end users by their survey status (if they are opted out from receiving surveys).

We recommend to iterate using created parameter if you need to get more data than what you get out of our pagination restriction.

Get a Specific End User by ID

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/2"

{
  "id": 2,
  "created_at": "2018-01-02 23:03:41 -0800",
  "updated_at": "2018-01-16 23:07:03 -0800",
  "email": "nps2@example.com",
  "last_surveyed": "2018-01-07 15:30:44 -0800",
  "external_created_at": 1515940485,
  "last_seen_at": null,
  "properties": {
    "country": "UK",
    "persona": "Individual",
    "pricing_plan": "Lite",
    "product_plan": "Mobile",
    "purchase_date": 1494569021,
    "revenue_amount": 10000
  },
  "phone_number": null,
  "external_id": "e9a12f9aa245cfd5",
  "last_response": {
    "id": 505550023,
    "score": 9,
    "text": "It's a great service.",
    "survey": {
      "channel": "mobile:ios"
    }
  },
  "settings": {
    "email_nps": true,
    "mobile_nps": true,
    "web_nps": true,
    "force_mobile_survey": null,
    "force_web_survey": null,
    "surveys_disabled_by_end_user": null
  }
}

This endpoint retrieves a specific end user by id.

HTTP Request

GET https://api.wootric.com/v1/end_users/<id>

URL Parameters

Parameter	Description
id	The ID of the end user to retrieve

Get a Specific End User by Email

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/nps2@example.com" -d "lookup_by_email=true"

{
  "id": 2,
  "created_at": "2018-01-02 23:03:41 -0800",
  "updated_at": "2018-01-16 23:07:03 -0800",
  "email": "nps2@example.com",
  "last_surveyed": "2018-01-07 15:30:44 -0800",
  "external_created_at": 1515940485,
  "last_seen_at": null,
  "properties": {
    "country": "UK",
    "persona": "Individual",
    "pricing_plan": "Lite",
    "product_plan": "Mobile",
    "purchase_date": 1494569021,
    "revenue_amount": 10000
  },
  "phone_number": null,
  "external_id": "e9a12f9aa245cfd5",
  "last_response": {
    "id": 505550023,
    "score": 9,
    "text": "It's a great service.",
    "survey": {
      "channel": "mobile:ios"
    }
  },
  "settings": {
    "email_nps": true,
    "mobile_nps": true,
    "web_nps": true,
    "force_mobile_survey": null,
    "force_web_survey": null,
    "surveys_disabled_by_end_user": null
  }
}

This endpoint retrieves a specific end user by email.

HTTP Request

GET https://api.wootric.com/v1/end_users/<email>?lookup_by_email=true

URL Parameters

Parameter	Description
email	The Email of the end user to retrieve
lookup_by_email (optional)	Looks up the user by email if true. Default value is false

Get a Specific End User by External ID

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/my-external-id-1234" -d "lookup_by_external_id=true"

{
  "id": 3,
  "created_at": "2018-01-02 23:03:41 -0800",
  "updated_at": "2018-01-16 23:07:03 -0800",
  "email": "nps3@example.com",
  "last_surveyed": "2018-01-07 15:30:44 -0800",
  "external_created_at": 1515940485,
  "last_seen_at": null,
  "properties": {
    "country": "UK",
    "persona": "Individual",
    "pricing_plan": "Lite",
    "product_plan": "Mobile",
    "purchase_date": 1494569021,
    "revenue_amount": 10000
  },
  "phone_number": null,
  "external_id": "my-external-id-1234",
  "last_response": {
    "id": 505550023,
    "score": 9,
    "text": "It's a great service.",
    "survey": {
      "channel": "mobile:ios"
    }
  },
  "settings": {
    "email_nps": true,
    "mobile_nps": true,
    "web_nps": true,
    "force_mobile_survey": null,
    "force_web_survey": null,
    "surveys_disabled_by_end_user": null
  }
}

This endpoint retrieves a specific end user by external_id.

HTTP Request

GET https://api.wootric.com/v1/end_users/<external_id>?lookup_by_external_id=true

URL Parameters

Parameter	Description
external_id	The External ID of the end user to retrieve
lookup_by_eternal_id (optional)	Looks up the user by external if true. Default value is false

Get a Specific End User by Phone Number

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/phone_number/+14155554131"

{
  "id": 2,
  "created_at": "2018-01-02 23:03:41 -0800",
  "updated_at": "2018-01-16 23:07:03 -0800",
  "email": "nps2@example.com",
  "last_surveyed": "2018-01-07 15:30:44 -0800",
  "external_created_at": 1515940485,
  "last_seen_at": null,
  "properties": {
    "country": "UK",
    "persona": "Individual",
    "pricing_plan": "Lite",
    "product_plan": "Mobile",
    "purchase_date": 1494569021,
    "revenue_amount": 10000
  },
  "phone_number": "+14155554131",
  "external_id": "e9a12f9aa245cfd5",
  "last_response": {
    "id": 505550023,
    "score": 9,
    "text": "It's a great service.",
    "survey": {
      "channel": "mobile:ios"
    }
  },
  "settings": {
    "email_nps": true,
    "mobile_nps": true,
    "web_nps": true,
    "force_mobile_survey": null,
    "force_web_survey": null,
    "surveys_disabled_by_end_user": null
  }
}

This endpoint retrieves a specific end user by phone number.

HTTP Request

GET https://api.wootric.com/v1/end_users/phone_number/<phone_number>

URL Parameters

Parameter	Description
phone_number	The Phone Number of the end user to retrieve. The phone number must be prefixed with ‘+’. If it’s just digits, it will look up by id.

Create End User

curl -X POST -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users" -d "email=enduser@example.com&last_surveyed=1423732280&properties[company]=TestCompany&properties[city]=San Francisco"

  {
    "id": 1,
    "email": "enduser@example.com",
    "last_surveyed": "2015-02-12T06:29:27.000-08:00",
    "external_created_at": null,
    "created_at" : "2015-02-12T06:29:27.000-08:00",
    "updated_at" : "2015-02-12T06:29:27.000-08:00",
    "user_id": 1,
    "properties": "{'company':'TestCompany', 'city':'San Francisco'}"
  }

This endpoint creates the end user.

HTTP Request

POST https://api.wootric.com/v1/end_users

URL Parameters

Parameter	Description
email	End user’s email address
last_surveyed (optional)	Date of last survey for the end user (UNIX Timestamp)
external_created_at (optional)	Date of creation of the end user in external application (UNIX Timestamp)
external_id (optional)	A unique string identifier
properties (optional)	Hash of additional properties

Update End User

curl -X PUT -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1" -d "email=enduser_new@example.com&properties[company]=NewCompany&properties[city]=New Reno"

  {
    "id": 1,
    "email": "enduser_new@example.com",
    "last_surveyed": "2015-02-12T06:29:27.000-08:00",
    "external_created_at": null,
    "created_at" : "2015-02-12T06:29:27.000-08:00",
    "updated_at" : "2015-02-12T06:29:27.000-08:00",
    "user_id": 1,
    "properties": "{'company':'NewCompany', 'city':'New Reno'}"
  }

This endpoint updates the end user with specified params.

HTTP Request

PUT https://api.wootric.com/v1/end_users/<END_USER_ID>

URL Parameters

Parameter	Description
END_USER_ID	The ID of the end user to update
email (optional)	End User’s Email Address
last_surveyed (optional)	Date of last survey for the end user (UNIX Timestamp)
external_created_at (optional)	Date of creation of the end user in external application (UNIX Timestamp)
external_id (optional)	A unique string identifier
properties (optional)	Hash of additional properties

Delete End User

# Using the end user's ID:

curl -X DELETE -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1"

# Using the end user's email address:

curl -X DELETE -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/user@domain.com"

  {
    "id": 1,
    "email": "enduser@example.com",
    "last_surveyed": "2015-02-12T06:29:27.000-08:00",
    "external_created_at": null,
    "created_at" : "2015-02-12T06:29:27.000-08:00",
    "updated_at" : "2015-02-12T06:29:27.000-08:00",
    "user_id": 1,
    "properties": "{'company':'TestCompany', 'city':'San Francisco'}"
  }

This endpoint marks the end user for deletion. Deletion would be scheduled the following day at 7 AM UTC. Depending on the size of our queues at the time it could take several hours to finish processing.

HTTP Request

DELETE https://api.wootric.com/v1/end_users/<end_user_id_or_email>

URL Parameters

Parameter	Description
end_user_id_or_email	The ID or the email of the end user to delete

Export specific End User’s data

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/2/export"

HTTP/1.1 202 Accepted

This endpoint schedules an export to be processed for the given end user ID, when the export file is ready we’ll send you an email with a link to the final JSON export file.

HTTP Request

GET https://api.wootric.com/v1/end_users/<id>/export

URL Parameters

Parameter	Description
id	The ID of the end user to export

Responses

Response Object

A response object has the following fields:

Attribute	Type	Description
id	integer	The ID of response
end_user_id	integer	The ID of end user
survey_id	integer	ID of the survey to which the response belongs
score	integer	The response’s score
text	text	The response’s comment
completed	boolean	Specifies if a response has been completed
excluded_from_calculations	boolean	Specifies if a response should be excluded from calculations
ip_address	text	The response’s IP address
origin_url	text	The response’s origin url
created_at	datetime	Datetime representation of when the response was created
updated_at	datetime	Datetime representation of when the response was last updated
tags	string array	The responses’s tags
end_user.properties	hash	The end user properties at the moment the survey was taken

Get All Responses

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/responses"

[
    {
        "id": 1,
        "end_user_id": 1,
        "survey_id": 1,
        "score": 0,
        "text": "Better performance would mean a higher score. Site is often slow.",
        "completed": false,
        "excluded_from_calculations": false,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 09:05:00 -0800",
        "updated_at": "2016-12-16 09:05:13 -0800",
        "tags": [
            "PERFORMANCE"
        ],
        "notes": [],
        "end_user": {
            "properties": {
                "persona": "Individual",
                "pricing_plan": "Small Business",
                "product_plan": "Mobile",
                "purchase_date": 1473177881,
                "revenue_amount": 5000,
                "items_array": "item1, item2"
            }
        }
    },
    {
        "id": 2,
        "end_user_id": 2,
        "survey_id": 2,
        "score": 10,
        "text": "Great service.",
        "completed": false,
        "excluded_from_calculations": false,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2017-12-16 09:10:43 -0800",
        "updated_at": "2017-12-16 09:11:00 -0800",
        "tags": [],
        "notes": [],
        "end_user": {
            "properties": {
                "persona": "Individual",
                "pricing_plan": "Small Business",
                "product_plan": "Web",
                "purchase_date": 1473177888,
                "revenue_amount": 5000,
                "items_array": "item1, item2"
            }
        }
    }
]

TIMESTAMP=$(date --date="2016-12-25" "+%s")
curl -X GET -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/responses" -d "created[lt]=$TIMESTAMP"

[
    {
        "id": 1,
        "end_user_id": 1,
        "survey_id": 1,
        "score": 0,
        "text": "Better performance would mean a higher score. Site is often slow.",
        "completed": false,
        "excluded_from_calculations": false,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 09:05:00 -0800",
        "updated_at": "2016-12-16 09:05:13 -0800",
        "tags": [
            "PERFORMANCE"
        ],
        "notes": [],
        "end_user": {
            "properties": {
                "persona": "Individual",
                "pricing_plan": "Small Business",
                "product_plan": "Mobile",
                "purchase_date": 1473177881,
                "revenue_amount": 5000,
                "items_array": "item1, item2"
            }
        }
    }
]

This endpoint retrieves all responses for a user.

HTTP Request

GET https://api.wootric.com/v1/responses

Scope Parameters

Scope parameters filter your responses and can also be chained together by passing multiple scope parameters in an array.

Parameter	Type	Default	Description
page (optional)	integer	1	Number of returned page, max 30
per_page (optional)	integer	25	Number of records returned on each page, max 50
created	hash	{}	Filter your responses by time of creation (UNIX timestamp type) - eq, lt, lte, gt, gte (`created[gt]=UNIX_TIMESTAMP &created[lt]=UNIX_TIMESTAMP`)
sort_order (optional)	string	desc	Order in which records are shown. Default is newest first. Options are `asc` or `desc`
excluded_from_calculations (optional)	boolean	false	Include/exclude responses that were invalidated

We recommend to iterate using created parameter if you need to get more data than what you get out of our pagination restriction.

Get All End User’s Responses

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1/responses"

[
    {
        "id": 1,
        "end_user_id": 1,
        "survey_id": 1,
        "score": 0,
        "text": "Better performance would mean a higher score. Site is often slow.",
        "completed": false,
        "excluded_from_calculations": false,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 09:05:00 -0800",
        "updated_at": "2016-12-16 09:05:13 -0800",
        "tags": [
            "PERFORMANCE"
        ],
        "notes": [],
        "end_user": {
            "properties": {
                "persona": "Individual",
                "pricing_plan": "Small Business",
                "product_plan": "Mobile",
                "purchase_date": 1473177881,
                "revenue_amount": 5000,
                "items_array": "item1, item2"
            }
        }
    },
    {
        "id": 3,
        "end_user_id": 1,
        "survey_id": 3,
        "score": 5,
        "text": "Customer support STILL hasn't gotten back to me.",
        "completed": false,
        "excluded_from_calculations": false,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 10:30:02 -0800",
        "updated_at": "2016-12-16 10:31:00 -0800",
        "tags": [
            "CALL"
        ],
        "notes": [],
        "end_user": {
            "properties": {
                "persona": "Individual",
                "pricing_plan": "Small Business",
                "product_plan": "Web",
                "purchase_date": 1473177888,
                "revenue_amount": 5000,
                "items_array": "item1, item2"
            }
        }
    }
]

This endpoint retrieves all responses for end user.

HTTP Request

GET https://api.wootric.com/v1/end_users/1/responses

Scope Parameters

Scope parameters filter your responses and can also be chained together by passing multiple scope parameters in an array.

Parameter	Type	Default	Description
page	integer	1	Number of returned page, max 30
per_page	integer	25	Number of records returned on each page, max 50
created	hash	{}	Filter your responses by time of creation (UNIX timestamp type) - eq, lt, lte, gt, gte (`created[gt]=UNIX_TIMESTAMP &created[lt]=UNIX_TIMESTAMP`)
sort_order (optional)	string	desc	Order in which records are shown. Default is newest first. Options are `asc` or `desc`
excluded_from_calculations (optional)	boolean	false	Include/exclude responses that were invalidated

We recommend to iterate using created parameter if you need to get more data than what you get out of our pagination restriction.

Get All Promoters Responses

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1/responses/promoters"

[
    {
        "id": 6,
        "end_user_id": 1,
        "survey_id": 6,
        "score": 9,
        "text": "Nice app.",
        "completed": false,
        "excluded_from_calculations": false,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 13:05:01 -0800",
        "updated_at": "2016-12-16 13:06:11 -0800",
        "tags": [
            "UX"
        ],
        "notes": [],
        "end_user": {
            "properties": {
                "persona": "Business User",
                "pricing_plan": "Small Business",
                "product_plan": "Mobile",
                "purchase_date": 1473177881,
                "revenue_amount": 5000,
                "items_array": "item1, item2"
            }
        }
    },
    {
        "id": 7,
        "end_user_id": 1,
        "survey_id": 7,
        "score": 10,
        "text": "Awesome service! The whole world should know about you guys.",
        "completed": false,
        "excluded_from_calculations": false,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 14:20:22 -0800",
        "updated_at": "2016-12-16 14:21:10 -0800",
        "tags": [],
        "notes": [],
        "end_user": {
            "properties": {
                "persona": "Business User",
                "pricing_plan": "Small Business",
                "product_plan": "Web",
                "purchase_date": 1473177888,
                "revenue_amount": 5000,
                "items_array": "item1, item2"
            }
        }
    }
]

This endpoint retrieves all promoters responses for end user.

HTTP Request

GET https://api.wootric.com/v1/end_users/1/responses/promoters

Scope Parameters

Scope parameters filter your promoters responses and can also be chained together by passing multiple scope parameters in an array.

Parameter	Type	Default	Description
page	integer	1	Number of returned page, max 30
per_page	integer	25	Number of records returned on each page, max 50
created	hash	{}	Filter your responses by time of creation (UNIX timestamp type) - eq, lt, lte, gt, gte (`created[gt]=UNIX_TIMESTAMP &created[lt]=UNIX_TIMESTAMP`)
sort_order (optional)	string	desc	Order in which records are shown. Default is newest first. Options are `asc` or `desc`

Get All Passives Responses

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1/responses/passives"

[
    {
        "id": 4,
        "end_user_id": 1,
        "survey_id": 4,
        "score": 7,
        "text": "Cool site.",
        "completed": false,
        "excluded_from_calculations": false,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 11:05:01 -0800",
        "updated_at": "2016-12-16 11:05:13 -0800",
        "tags": [
            "UX"
        ],
        "notes": [],
        "end_user": {
            "properties": {
                "persona": "Individual",
                "pricing_plan": "Small Business",
                "product_plan": "Mobile",
                "purchase_date": 1473177881,
                "revenue_amount": 5000,
                "items_array": "item1, item2"
            }
        }
    },
    {
        "id": 5,
        "end_user_id": 1,
        "survey_id": 5,
        "score": 8,
        "text": "Good service.",
        "completed": false,
        "excluded_from_calculations": false,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 12:00:02 -0800",
        "updated_at": "2016-12-16 12:01:00 -0800",
        "tags": [],
        "notes": [],
        "end_user": {
            "properties": {
                "persona": "Business User",
                "pricing_plan": "Small Business",
                "product_plan": "Web",
                "purchase_date": 1473177888,
                "revenue_amount": 5000,
                "items_array": "item1, item2"
            }
        }
    }
]

This endpoint retrieves all passives responses for end user.

HTTP Request

GET https://api.wootric.com/v1/end_users/1/responses/passives

Scope Parameters

Scope parameters filter your passives responses and can also be chained together by passing multiple scope parameters in an array.

Parameter	Type	Default	Description
page	integer	1	Number of returned page, max 30
per_page	integer	25	Number of records returned on each page, max 50
created	hash	{}	Filter your responses by time of creation (UNIX timestamp type) - eq, lt, lte, gt, gte (`created[gt]=UNIX_TIMESTAMP &created[lt]=UNIX_TIMESTAMP`)
sort_order (optional)	string	desc	Order in which records are shown. Default is newest first. Options are `asc` or `desc`

Get All Detractors Responses

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1/responses/detractors"

[
    {
        "id": 1,
        "end_user_id": 1,
        "survey_id": 1,
        "score": 0,
        "text": "Better performance would mean a higher score. Site is often slow.",
        "completed": false,
        "excluded_from_calculations": false,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 09:05:00 -0800",
        "updated_at": "2016-12-16 09:05:13 -0800",
        "tags": [
            "PERFORMANCE"
        ],
        "notes": [],
        "end_user": {
            "properties": {
                "persona": "Individual",
                "pricing_plan": "Small Business",
                "product_plan": "Mobile",
                "purchase_date": 1473177881,
                "revenue_amount": 5000,
                "items_array": "item1, item2"
            }
        }
    },
    {
        "id": 3,
        "end_user_id": 1,
        "survey_id": 3,
        "score": 5,
        "text": "Customer support STILL hasn't gotten back to me.",
        "completed": false,
        "excluded_from_calculations": false,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 10:30:02 -0800",
        "updated_at": "2016-12-16 10:31:00 -0800",
        "tags": [
            "CALL"
        ],
        "notes": [],
        "end_user": {
            "properties": {
                "persona": "Individual",
                "pricing_plan": "Small Business",
                "product_plan": "Web",
                "purchase_date": 1473177888,
                "revenue_amount": 5000,
                "items_array": "item1, item2"
            }
        }
    }
]

This endpoint retrieves all detractors responses for end user.

HTTP Request

GET https://api.wootric.com/v1/end_users/1/responses/detractors

Scope Parameters

Scope parameters filter your detractors responses and can also be chained together by passing multiple scope parameters in an array.

Parameter	Type	Default	Description
page	integer	1	Number of returned page, max 30
per_page	integer	25	Number of records returned on each page, max 50
created	hash	{}	Filter your responses by time of creation (UNIX timestamp type) - eq, lt, lte, gt, gte (`created[gt]=UNIX_TIMESTAMP &created[lt]=UNIX_TIMESTAMP`)
sort_order (optional)	string	desc	Order in which records are shown. Default is newest first. Options are `asc` or `desc`

Get a Specific Response

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/2/responses/2"

{
    "id": 2,
    "end_user_id": 2,
    "survey_id": 2,
    "score": 10,
    "text": "Great service.",
    "completed": false,
    "excluded_from_calculations": false,
    "ip_address": "127.0.0.1",
    "origin_url": "https://wootric.com",
    "created_at": "2016-12-16 09:10:43 -0800",
    "updated_at": "2016-12-16 09:11:00 -0800",
    "tags": [],
    "notes": [],
    "end_user": {
        "properties": {
            "persona": "Individual",
            "pricing_plan": "Small Business",
            "product_plan": "Web",
            "purchase_date": 1473177888,
            "revenue_amount": 5000,
            "items_array": "item1, item2"
        }
    }
}

This endpoint retrieves a specific response.

HTTP Request

GET https://api.wootric.com/v1/end_users/<end_user_id>/responses/<id>

URL Parameters

Parameter	Type	Description
end_user_id	integer	The ID of the end user
id	integer	The ID of the decline to retrieve

Create Response

curl -X POST -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1/responses" -d "score=5&text=test response&ip_address=192.168.0.1&origin_url=http://example.com"

This endpoint creates a response for the end user.

HTTP Request

POST https://api.wootric.com/v1/end_users/<end_user_id>/responses

URL Parameters

Parameter	Type	Description
end_user_id	integer	The ID of the end user
score	integer	The end user response score (values from 0 to 10)
ip_address	text	IP address the response originated from
origin_url	text	URL the response originated from
text (optional)	text	The end user comment to the response
created_at (optional)	integer (UNIX timestamp)	If present, will set ‘created_at’ of newly created decline to provided value
end_user.properties (optional)	hash	An object containing the current properties for this end user. If supplied, the end user profile will be updated and the new properties will be associated to this response.

Update Response

curl -X PUT -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/responses/1" -d "completed=true&excluded_from_calculations=false"

This endpoint updates an existing response.

HTTP Request

PUT https://api.wootric.com/v1/responses/<id>

URL Parameters

Parameter	Type	Description
id	integer	The ID of the response to update
completed (optional)	boolean	Indicates if the response is complete
excluded_from_calculations (optional)	boolean	Indicates if the response is invalid
end_user.properties (optional)	hash	An object containing the new set of properties for this response. This will only update the properties that the end user had at this point in time. The current end user properties won’t be updated. Since this feature allows to edit historical data, it’s not enabled by default. Please contact us to enable it. A 423 error will be returned when attempting to use this feature if it’s not enabled.

Delete Response

curl -X DELETE -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1/responses/1"

This endpoint deletes an end user response.

HTTP Request

DELETE https://api.wootric.com/v1/end_users/<end_user_id>/responses/<response_id>

URL Parameters

Parameter	Type	Description
end_user_id	integer	The ID of the end user
response_id	integer	The ID of the response to delete

Declines

Decline Object

A decline object has the following fields:

Attribute	Type	Description
id	integer	The ID of decline
end_user_id	integer	The ID of end user
survey_id	integer	ID of the survey to which the decline belongs
ip_address	text	The decline’s IP address
origin_url	text	The decline’s origin url
created_at	datetime	Datetime representation of when the decline was created
updated_at	datetime	Datetime representation of when the decline was last updated
end_user.properties	hash	The end user properties at the moment the survey was taken

Get All Declines

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/declines"

[
    {
        "id": 1,
        "end_user_id": 1,
        "survey_id": 10,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 14:20:43 -0800",
        "updated_at": "2016-12-16 14:20:43 -0800",
        "end_user": {
            "properties": {
                "persona": "Individual",
                "pricing_plan": "Small Business",
                "product_plan": "Mobile",
                "purchase_date": 1473177881,
                "revenue_amount": 5000
            }
        }
    },
    {
        "id": 2,
        "end_user_id": 2,
        "survey_id": 11,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 14:21:10 -0800",
        "updated_at": "2016-12-16 14:21:10 -0800",
        "end_user": {
            "properties": {
                "persona": "Business User",
                "pricing_plan": "Small Business",
                "product_plan": "Mobile",
                "purchase_date": 1473177881,
                "revenue_amount": 5000
            }
        }
    }
]

This endpoint retrieves all declines for the user.

HTTP Request

GET https://api.wootric.com/v1/declines

Scope Parameters

Scope parameters filter your declines and can also be chained together by passing multiple scope parameters in an array.

Parameter	Type	Default	Description
page	integer	1	Number of returned page, max 30
per_page	integer	25	Number of records returned on each page, max 50
created	hash	{}	Filter your declines by time of creation (UNIX timestamp type) - eq, lt, lte, gt, gte (`created[gt]=UNIX_TIMESTAMP &created[lt]=UNIX_TIMESTAMP`)
sort_order (optional)	string	desc	Order in which records are shown. Default is newest first. Options are `asc` or `desc`

We recommend to iterate using created parameter if you need to get more data than what you get out of our pagination restriction.

Get All End User’s Declines

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1/declines"

[
    {
        "id": 1,
        "end_user_id": 1,
        "survey_id": 10,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 14:20:43 -0800",
        "updated_at": "2016-12-16 14:20:43 -0800",
        "end_user": {
            "properties": {
                "persona": "Individual",
                "pricing_plan": "Small Business",
                "product_plan": "Mobile",
                "purchase_date": 1473177881,
                "revenue_amount": 5000
            }
        }
    },
    {
        "id": 3,
        "end_user_id": 1,
        "survey_id": 12,
        "ip_address": "127.0.0.1",
        "origin_url": "https://wootric.com",
        "created_at": "2016-12-16 14:22:41 -0800",
        "updated_at": "2016-12-16 14:22:41 -0800",
        "end_user": {
            "properties": {
                "persona": "Individual",
                "pricing_plan": "Small Business",
                "product_plan": "Mobile",
                "purchase_date": 1473177881,
                "revenue_amount": 5000
            }
        }
    }
]

This endpoint retrieves all declines for end user.

HTTP Request

GET https://api.wootric.com/v1/end_users/1/declines

Scope Parameters

Scope parameters filter your declines and can also be chained together by passing multiple scope parameters in an array.

Parameter	Type	Default	Description
page	integer	1	Number of returned page, max 30
per_page	integer	25	Number of records returned on each page, max 50
created	hash	{}	Filter your declines by time of creation (UNIX timestamp type) - eq, lt, lte, gt, gte (`created[gt]=UNIX_TIMESTAMP &created[lt]=UNIX_TIMESTAMP`)
sort_order (optional)	string	desc	Order in which records are shown. Default is newest first. Options are `asc` or `desc`

Get a Specific Decline

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1/declines/1"

{
    "id": 1,
    "end_user_id": 1,
    "survey_id": 10,
    "ip_address": "127.0.0.1",
    "origin_url": "https://wootric.com",
    "created_at": "2016-12-16 14:20:43 -0800",
    "updated_at": "2016-12-16 14:20:43 -0800",
    "end_user": {
        "properties": {
            "persona": "Individual",
            "pricing_plan": "Small Business",
            "product_plan": "Mobile",
            "purchase_date": 1473177881,
            "revenue_amount": 5000
        }
    }
}

This endpoint retrieves a specific decline.

HTTP Request

GET https://api.wootric.com/v1/end_users/<end_user_id>/declines/<id>

URL Parameters

Parameter	Type	Description
end_user_id	integer	The ID of the end user
id	integer	The ID of the decline to retrieve

Create Decline

curl -X POST -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1/declines"

This endpoint creates a decline for the end user.

HTTP Request

POST https://api.wootric.com/v1/end_users/<end_user_id>/declines

URL Parameters

Parameter	Type	Description
end_user_id	integer	The ID of the end user
origin_url (optional)	string	URL of the decline origin
created_at (optional)	integer (UNIX timestamp)	If present, will set ‘created_at’ of newly created decline to provided value
end_user.properties (optional)	hash	An object containing the current properties for this end user. If supplied, the end user profile will be updated and the new properties will be associated to this decline.

Update Decline

curl -X PUT -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/declines/1" -d "end_user[properties][persona]=Individual"

This endpoint updates an existing decline.

HTTP Request

PUT https://api.wootric.com/v1/responses/<id>

URL Parameters

Parameter	Type	Description
id	integer	The ID of the response to update
end_user.properties (optional)	hash	An object containing the new set of properties for this decline. This will only update the properties that the end user had at this point in time. The current end user properties won’t be updated. Since this feature allows to edit historical data, it’s not enabled by default. Please contact us to enable it. A 423 error will be returned when attempting to use this feature if it’s not enabled.

Delete Decline

curl -X DELETE -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1/declines/1"

This endpoint deletes a decline for the end user.

HTTP Request

DELETE https://api.wootric.com/v1/end_users/<end_user_id>/declines/<decline_id>

URL Parameters

Parameter	Type	Description
end_user_id	integer	The ID of the end user
decline_id	integer	The ID of the decline to delete

End User Settings

End User Settings Object

A end user settings object has the following fields:

Attribute	Type	Description
id	integer	The ID of end user settings
end_user_id	integer	The ID of end user
created_at	datetime	Datetime representation of when the end user settings were created
updated_at	datetime	Datetime representation of when the end user settings was last updated
email_nps	boolean	Specifies whether end user should receive a survey through an email
mobile_nps	boolean	Specifies whether end user should receive a survey through our mobile SDK
web_nps	boolean	Specifies whether end user should receive a survey through our web SDK
force_web_survey	boolean	Flag to override sampling settings. It will make the end user immediately available for a survey via our web SDK
force_mobile_survey	boolean	Flag to override sampling settings. It will make the end user immediately available for a survey via our mobile SDK

Get Specific End User Settings

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1/settings"

  {
    "id":1,
    "end_user_id":2,
    "created_at":"2015-04-20 04:46:51-08:00",
    "updated_at":"2015-04-20 04:46:51-08:00",
    "email_nps":true
  }

This endpoint retrieves a specific end users settings.

HTTP Request

GET https://api.wootric.com/v1/end_users/<end_user_id>/settings

URL Parameters

Parameter	Description
end_user_id	The ID of the end user

Update End User Settings

curl -X PUT -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/end_users/1/settings" -d "email_nps=false&force_web_survey=true"

  {
    "end_user_id":1,
    "id":2,
    "email_nps":false,
    "created_at":"2015-04-20T04:55:58.741-08:00",
    "updated_at":"2015-04-20T04:55:58.755-08:00"
  }

This endpoint updates the end users settings with specified params.

HTTP Request

PUT https://api.wootric.com/v1/end_users/<end_user_id>/settings

URL Parameters

Parameter	Description
end_user_id	The ID of the end user to update
email_nps (optional)	whether or not end user should receive NPS survey through an email

Metrics

NPS Object

An NPS object has the following fields:

Attribute	Type	Description
nps	integer	NPS for a given date range
responses	integer	Number of responses for a given date range
detractors	integer	Number of detractors for a given date range
passives	integer	Number of passives for a given date range
promoters	integer	Number of promoters for a given date range
response_rate	integer	Response rate percentage for a given date range
email_response_rate	integer	Email response rate percentage for a given date range

Get NPS summary

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/nps_summary"

# With params

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/nps_summary?date%5Bstart%5D='YYYY-MM-DD'&date%5Bend%5D='YYYY-MM-DD'"

  {
    "nps": 55,
    "responses": 75,
    "detractors": 5,
    "passives": 24,
    "promoters": 46,
    "response_rate": 92,
    "email_response_rate": 0
  }

This endpoint retrieves the NPS summary for the specified date range. If no date range is specified, the API returns NPS summary for the last month.

HTTP Request

GET https://api.wootric.com/v1/nps_summary

URL Parameters

Parameter	Type	Default	Description
date (optional)	hash	{}	NPS summary by start date (optional) and end date (optional) (`date[start]='YYYY-MM-DD'&date[end]='YYYY-MM-DD'`)

Segments

Segment Object

A Segment object has the following fields:

Attribute	Type	Description
name	string	Name of the segment
data_type	string	One of `string`, `date` or `integer` representing the segment data type
created_at	datetime	Datetime representation of when the segment was created

Get All Segments

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/segments"

[
  {
    "name": "persona",
    "data_type": "string",
    "created_at": "2017-02-01 12:12:50 -0800"
  },
  {
    "name": "pricing_plan",
    "data_type": "string",
    "created_at": "2017-02-01 12:12:50 -0800"
  },
  {
    "name": "product_plan",
    "data_type": "string",
    "created_at": "2017-02-01 12:12:50 -0800"
  },
  {
    "name": "purchase_date",
    "data_type": "date",
    "created_at": "2017-02-01 12:12:50 -0800"
  },
  {
    "name": "revenue_amount",
    "data_type": "integer",
    "created_at": "2017-02-01 12:12:50 -0800"
  }
]

This endpoint retrieves all segments for an account.

HTTP Request

GET https://api.wootric.com/v1/segments

Errors

The Wootric API uses the following error codes:

Error Code	Meaning
400	Bad Request – Your request is incorrect
401	Unauthorized – Your access token is wrong
404	Not Found – The specified resource could not be found
500	Internal Server Error – We had a problem with our server. Try again later.

Survey Templates

This endpoint retrieves information about all your Survey Templates.

# Example with custom product_name and audience_text

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v1/survey_templates?access_token=account_access_token"

// Response

{
  "default_survey_template_id": XXXX,
  "survey_templates": [
    {
      "id": XXXX,
      "name": "Your default NPS survey",
      "default_language": "en",
      "languages": [
        {"code":"en","name":"English"},
        {"code":"es","name":"Spanish"}
      ],
      "non_configured_language_count":1,
      "custom_samplings":[]
    },
    {
      "id": XXXX,
      "name":"Alternate Survey",
      "default_language":"es",
      "languages": [
        {"code":"es","name":"Spanish"},
        {"code":"en","name":"English"}
      ],
      "non_configured_language_count": 2,
      "custom_samplings":[]
    }
  ]
}

Email Survey

// Basic Example

curl "https://api.wootric.com/v1/email_survey" \
  -d "access_token=myaccesstoken" \
  -d "emails[]=john@example.com" \
  -d "emails[]=jane@example.com" \
  -d "survey_immediately=true" \
  -d "survey_settings[custom_messages][followup_text]=Thank you!" \
  -d "subject=Would you mind sharing your thoughts about our service?" \
  -d "intro=We want you to be our customer for life. That's why your opinion matters."

Maximum of 100 emails per request.
We will automatically create an end user if they don’t exist.

Param	Type	Description
emails	String Array	End user emails to survey
survey_immediately	Boolean	Override eligibility check
end_user	Hash	End user properties name as `String`
survey_settings	Hash	See survey_settings parameters below
subject	String	Override default subject line (standard NPS/CES/CSAT question used by default). Can handle placeholder values surrounded by {{my_value}}
intro	String	Intro message for your email. Displayed between logo and question. Default: none. Can handle placeholder values surrounded by {{my_value}}
context	Hash Array	Array of hashes containing the values to be replaced in subject and/or intro
senders_name	String	Override senders name
reply_to_email	String	Override reply-to email
delay	Integer	Days we will wait before sending the survey. Delay is optional and it must be between 1 and 31 days.
external_ids	String Array	External ids for each end user.

Email Survey showing Subject and Intro: Compact Survey

# Example with end_user properties

curl "https://api.wootric.com/v1/email_survey" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "emails[]=john@example.com" \
  -d "survey_immediately=true" \
  -d "survey_settings[custom_messages][followup_text]=Thank you!" \
  -d "end_user[properties][campaign_name]=Campaign Name&end_user[properties][campaign_type]=Campaign Type"

# Example with custom intro and subject

curl "https://api.wootric.com/v1/email_survey" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "emails[]=john@example.com" \
  -d "emails[]=martin@example.com" \
  -d "survey_immediately=true" \
  -d "survey_settings[logo_url]=https://company_logo_url.com" \
  -d "survey_settings[custom_messages][followup_text]=Thank you!" \
  -d "end_user[properties][campaign_name]=Campaign Name&end_user[properties][campaign_type]=Campaign Type" \
  -d "subject=Would you mind sharing your thoughts about our {{service}}?" \
  -d "intro=Tell us why you like {{color}} so much." \
  -d "context[][service]=internet, laundry" \
  -d "context[][color]=red, blue"

# Example with senders name and reply-to email

curl "https://api.wootric.com/v1/email_survey" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "emails[]=john@example.com" \
  -d "survey_immediately=true" \
  -d "senders_name=Sender Name" \
  -d "reply_to_email=replyto@email.com"

# Example of an 8 day delay

curl "https://api.wootric.com/v1/email_survey" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "emails[]=john@example.com" \
  -d "survey_immediately=true" \
  -d "delay=8"

# Example of sampling override.

curl "https://api.wootric.com/v1/email_survey" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "emails[]=john@example.com" \
  -d "survey_settings[sampling][first_survey_delay]=10" \
  -d "survey_settings[sampling][registered_percent]=50"

# Example of multiple external_ids.

curl "https://api.wootric.com/v1/email_survey" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "emails[]=john@example.com,harry@example.com" \
  -d "external_ids[]=42-JOHN-USA,21-HARRY-UK"

survey_settings parameters

Param	Type	Description
language	String
logo_url	String
audience_text	String
product_name	String
custom_messages	Hash	See custom_messages parameters below
sampling	Hash	See sampling parameters below

custom_messages parameters

Param	Type
followup_text	String
detractor_followup_text	String
passive_followup_text	String
promoter_followup_text	String
prompt_text	String
detractor_prompt_text	String
passive_prompt_text	String
promoter_prompt_text	String

sampling parameters

You may use these parameters to overwrite the settings you have in your Wootric settings panel.

Param	Type	Description
first_survey_delay	Integer	Number of days that have to pass since end user’s created_at to show a survey
response_throttle	Integer	Number of days that have to pass after answering a survey to be eligible again
decline_throttle	Integer	Number of days that have to pass after declining a survey to be eligible again
registered_percent	Integer	Chances from 0 to 100 to serve a survey

Email Survey CSV

This endpoint will let you send email surveys in bulk using a CSV file. The CSV file should contain at least an email column, the rest of the columns are either special columns (detailed below) or custom properties that will be added to the email surveys.

// Basic Example using a CSV file (FILE.csv)

curl "https://api.wootric.com/v1/email_survey_csv" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "csv=FILE.csv"
  -d "survey_immediately=true" \
  -d "survey_settings[custom_messages][followup_text]=Thank you!" \
  -d "subject=Would you mind sharing your thoughts about our service?" \
  -d "intro=We want you to be our customer for life. That's why your opinion matters."

CSV file

email,segment1,segment2
email@email.com,segment1_value,segment2_value
email2@email.com,2segment1_value,2segment2_value
email3@email.com,3segment1_value,3segment2_value
email4@email.com,4segment1_value,4segment2_value

Example:

email,First Name, Last Name, Company Name
bob@inmoment.com,Bob,Smith,InMoment
jane@inmoment.com,Jane,Jones,InMoment
enrique@gmail.com,Enrique,Rodriguez,ER Inc.

Maximum of 5000 rows per request.
We will automatically create end users if they don’t exist.

CSV Columns

The first column of the CSV needs to be the email address and the column should be named email
All the other columns will be treated as string properties unless they have a special column name

Special columns names

Context variables

___context:var

These “context” variables, if present, will be available as variables to use in variable interpolation. For example, if you pass the subject parameter as “Hello {{first_name}}!” and you add a context variable column to your CSV file (___context:first_name), then each email survey (each row in the file) will use the value of the ___context:first_name as first_name and that value will be interpolated to resolve the email subject. Resulting in email subjects like “Hello John!”, “Hello Anne”, etc.

Language

Naming a column Language creates a property.
Naming a column ___language does not create a property if the language is multi_language.

The language column corresponds to the language code that should be found in each row of the file.

This is only for multi-language accounts.
To use a multi-language column it’s required to send survey_settings[language] set to multi_language and pass the survey template used as a parameter survey_settings[survey_template_id]. Check out the survey templates API to see the list of survey templates and available languages configured in your account.
All language code values for this column in the CSV should match exactly the language codes configured for the survey template you are using.

Column Naming Reminder:

Integer column names should end with “_amount” (e.g.price_amount).
Date column names should end with “_date” (e.g.start_date).

Param	Type	Description
csv	File	CSV file with end user data OR a Base64 encoded String with CSV data (“Base 64 Encoding with URL and Filename Safe Alphabet” in RFC 4648)
subject	String	Override default subject line (standard NPS/CES/CSAT question used by default). Can handle placeholder values surrounded by {{my_value}}
intro	String	Intro message for your email. Displayed between logo and question. Default: none. Can handle placeholder values surrounded by {{my_value}}
context	Hash Array	Array of hashes containing the values to be replaced in subject and/or intro
senders_name	String	Override senders name
reply_to_email	String	Override reply-to email
delay	Integer	Days we will wait before sending the survey. Delay is optional and it must be between 1 and 31 days.
delivery_time	String	UTC time of the day to deliver emails (format: hh:mm) in 24 hs format.
custom_sender_email	String	Custom sender email.
send_to_email_field	String	Column containing the email address of the receiver.
unique_identifier_field	String	Field used to set the email of the end user (require send_to_email_field).
survey_immediately	Boolean	Override eligibility check
survey_settings	Hash	See survey_settings parameters below

Email Survey showing Subject and Intro: Compact Survey

# Example with custom intro and subject

curl "https://api.wootric.com/v1/email_survey_csv" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "csv=FILE.csv" \
  -d "survey_immediately=true" \
  -d "survey_settings[logo_url]=https://company_logo_url.com" \
  -d "survey_settings[custom_messages][followup_text]=Thank you!" \
  -d "subject=Would you mind sharing your thoughts about our {{service}}?" \
  -d "intro=Tell us why you like {{color}} so much."

CSV

email,segment1,segment2,___context:service,___context:color
email@email.com,segment1_value,segment2_value,internet,red
email2@email.com,2segment1_value,2segment2_value,laundry,blue

# Example with custom product_name and audience_text

curl "https://api.wootric.com/v1/email_survey_csv" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "csv=FILE.csv" \
  -d "survey_immediately=true" \
  -d "survey_settings[audience_text]={{region}} division" \
  -d "survey_settings[product_name]=Our Product {{color}}"

CSV

email,segment1,segment2,___context:region,___context:color
email@email.com,segment1_value,segment2_value,southern,red
email2@email.com,2segment1_value,2segment2_value,northern,blue

# Example with multi-language
# Keep in mind that you will need to provide a valid survey_template_id that has settings
# for each one of the languages used in the CSV file (in the "___language" column)

curl "https://api.wootric.com/v1/email_survey_csv" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "csv=FILE.csv" \
  -d "survey_immediately=true" \
  -d "survey_settings[survey_template_id]=888"

CSV

email,segment1,segment2,___language
email@email.com,segment1_value,segment2_value,en
email2@email.com,2segment1_value,2segment2_value,es
email3@email.com,3segment1_value,3segment2_value,en

# Example with senders name and reply-to email

curl "https://api.wootric.com/v1/email_survey_csv" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "csv=FILE.csv" \
  -d "survey_immediately=true" \
  -d "senders_name=Sender Name" \
  -d "reply_to_email=replyto@email.com"

CSV

# Example of an 8 days delay

curl "https://api.wootric.com/v1/email_survey_csv" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "csv=FILE.csv" \
  -d "survey_immediately=true" \
  -d "delay=8"

# Example of sampling override.

curl "https://api.wootric.com/v1/email_survey_csv" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "csv=FILE.csv" \
  -d "survey_settings[sampling][first_survey_delay]=10" \
  -d "survey_settings[sampling][registered_percent]=50"

CSV

email,Region,Country,Project Name
user1@gmail.com,EMEA,USA,Project One
user2@gmail.com,LATAM,Argentina,Assessment Project

Corresponding BASE64_STRING:

“ZW1haWwsUmVnaW9uLENvdW50cnksUHJvamVjdCBOYW1lCnVzZXIxQGdt
YWlsLmNvbSxFTUVBLFVTQSxQcm9qZWN0IE9uZQp1c2VyMkBnbWFpbC5jb
20sTEFUQU0sQXJnZW50aW5hLEFzc2Vzc21lbnQgUHJvamVjdA==”

# Example using a Base64 encoded string

curl "https://api.wootric.com/v1/email_survey_csv" \
  -d "access_token=XXXXXXXXXXXXXXXX" \
  -d "csv=$BASE64_STRING" \
  -d "survey_immediately=true"

survey_settings parameters

Param	Type	Description
logo_url	String
survey_template_id	Integer
audience_text	String	Can handle placeholder values surrounded by {{my_value}}
product_name	String	Can handle placeholder values surrounded by {{my_value}}
custom_messages	Hash	See custom_messages parameters below
sampling	Hash	See sampling parameters below

custom_messages parameters

Param	Type
followup_text	String
detractor_followup_text	String
passive_followup_text	String
promoter_followup_text	String
prompt_text	String
detractor_prompt_text	String
passive_prompt_text	String
promoter_prompt_text	String

sampling parameters

You may use these parameters to overwrite the settings you have in your Wootric settings panel.

Param	Type	Description
first_survey_delay	Integer	Number of days that have to pass since end user’s created_at to show a survey
response_throttle	Integer	Number of days that have to pass after answering a survey to be eligible again
decline_throttle	Integer	Number of days that have to pass after declining a survey to be eligible again
registered_percent	Integer	Chances from 0 to 100 to serve a survey

Email Stats

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v2/email_stats"

{
  "email_stats": {
    "send_date": "Aug  3, 2023-Sep  3, 2024",
    "send_requests": 7,
    "emails_sent": 5,
    "delivered": 5,
    "delivered_percentage": "100.0%",
    "bounce_rate": 0,
    "bounce_rate_percentage": "0.0%",
    "open_rate": "60%",
    "response_rate": "0%",
    "not_eligible": "2 (29%)",
    "raw_results": {
      "processed": 5,
      "bounce": 0,
      "dropped": 0,
      "delivered": 5,
      "opted_out": 2,
      "not_delivered": 0,
      "open": 3,
      "spamreport": 0,
      "not_eligible": 0,
      "total_surveys": 5,
      "total_responses": 0,
      "sart_date": "2023-08-03T00:00:00-07:00",
      "end_date": "2024-09-03T23:59:59-07:00"
    }
  },
  "initial_send": null,
  "reminder_send": null
}

Returns email stats information depending on the date_range selected.

Param	Type	Description
date_range	Hash	See date_range parameters below

Sources

curl -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v2/email_stats/sources"


{
  "ongoing": [
    {
      "id": "email_api",
      "name": "Email API *"
    },
    {
      "id": "webhook_trigger",
      "name": "Webhook Trigger *"
    }
  ],
  "sends": [
    {
      "id": 1,
      "name": "Q1_file.csv",
      "date": "Jan 11, 2024  9:01AM"
    },
    {
      "id": 2,
      "name": "Q2_file.csv",
      "date": "Apr 14, 2024  9:04AM"
    },
    {
      "id": 3,
      "name": "Q3_file.csv",
      "date": "Jul 09, 2024  10:04AM"
    }
  ]
}

Returns the names and IDs of the sources of the email sends.

Bounce report

curl -XPOST -H "Authorization: Bearer myaccesstoken" "https://api.wootric.com/v2/email_stats/bounce_report"


null

Generates and emails a bounce report to the current user if the access token belongs to one, or the owner of the account if the access token was generated with grant_type=client_credentials.

Param	Type	Description
date_range	Hash	See date_range parameters below
source	String	Source of the bounce report (email_api, webhook_trigger or ID of the email send)

date_range

Param	Type	Description
start_date	String	Start date string with format YYYY-MM-DD (e.g. 2024-08-04)
end_date	String	End date string with format YYYY-MM-DD (e.g. 2024-08-04)