The AskNicely API is a RESTful API, returning JSON responses.

API Keys

• AskNicely only requires a single API key N/A to authenticate your request.
• Every AskNicely user is assigned their own API key, if you want to isolate API requests, create a new user.

Authenticating

• Include your API key as a header X-apikey: N/A to authenticate your request.

Contact Rules (Found on the Send page)

• The API will only obey the first contact rule found on the send page
  • i.e. "Wait at least X days before contacting a customer again"
• The API ignores the second rule
  • i.e. "For newly added contacts, wait X days…"

Adding your own Custom Data

You can add your own custom data fields to every contact, by simply sending along your desired field name, in snake_case suffixed with an `_c`.
For example, if you would like your contacts to show a custom data field for their "Branch Location", please send along a parameter of branch_location_c: Portland

Errors

{
    "success": false,
    "msg": "We could not find the api key, or it was not set []"
}

Rate Limits

RateLimit-Req10s-Limit:200
RateLimit-Req10s-Remaining:197
RateLimit-Req60s-Limit:1000
RateLimit-Req60s-Remaining:997

If a rate limit is hit, a HTTP 429 response is returned.
A blocked API request would contain a clear JSON response in the body as well as the Retry-After: Response Header.

{
    "success": false,
    "msg": "Rate limit hit: reduce the rate of requests and retry",
    "type": "req-10s",
    "count": 201,
    "limit": 200
}

Please note that there is a different a rate limit applied for calls to /contact/trigger! If you hit this limit, consider sending your data in bulk to /contacts/add.
A blocked API request would contain a clear JSON response in the body as well as the Retry-After: Response Header.

RateLimit-Req10s-Limit:100
RateLimit-Req60s-Limit:500