Build unique apps powered by advanced demographic prediction AI
Short development time to get started quickly
Dozens of ready-to-use SDKs
Two-way sync with Demografy dashboard so you can work both in Demografy and your app
Demografy API
Basics
Authentication
Rate Limits
Use Cases
API Reference
Webhook
Client SDKs ({{docsCtrl.clientList.length}})
Testing
Basics
The Demografy API is built to programmatically exchange data with the Demografy platform. Demografy API is an HTTP-based REST API that can be used to programmatically segment marketing lists and sync data between Demografy and third-party apps and services.
The Demografy API is HTTP-based meaning your API client can be built using any programming language that has an HTTP support.
Authentication
Authentication is performed using registered API key sent as URL parameter. In development mode you can use your test API key to query and retrieve test data from API without hitting rate limits.
Rate limits
All production API calls are subject to rate limits or number of available API calls you can make. Rate limits depend on your subscription plan and affect your ability to use API. You will receive iformation about available rate limits in each API response.
Client SDKs
The Demografy API provides 57 autogenerated up-to-date client SDKs for different platforms and programming languages.
Money
All money values transmitted to and from the Demografy API are in integers in minor currency unit format. E.g. $50.25 is formatted as 5025. Currency symbols are dropped since only USD is currently supported.
Numbers
All numbers transmitted to and from the Demografy API are in en-US number format. E.g. period is used as decimal separator (1.5).
Dates
All dates are in UTC timezone and are ISO8601 format.
Languages
Currently only US English is supported.
API responses
All responses are wrapped in JSON objects containing information about data returned from API, error if any and rate limits.
{
  "data": {
    
    }
  },
  "error": {
    "message": null,
    "code": null
  },
  "rateLimits": {
    "hourLimitsLeft": 100,
    "dayLimitsLeft": 1000,
    "monthLimitsLeft": 14000,
    "isBlocked": false,
    "isRateLimited": false,
    "nextAllowedCall": "2020-08-14T23:33:02.4987094Z"
  }
}
If error occured you will get error property instead of data and vise versa. RateLimits property will be available in both succeed and failed responses.
Authentication
To authorize requests the Demografy API uses URL-based API key authentication. Meaning that your API key should be included in service URL as apiKey URL parameter. API key is a unqique base64 string. During development phase you can generate and use test API key to play with API. As soon as you go live you need a production API key to get access to live platform. Both test and production API keys are rate limited depending on your plan.
Rate Limits
All API requests are subject to rate limits. A rate limit is the number of API calls your app can make within a given time window. If this limit is exceeded the app will be temporary blocked and API requests will fail untill the end of time window.
API call is a single HTTP request to one of the API endpoints. Each push notification to your webhook/callback (if implemented) also counts as API call.
There are different time windows at which different rate limits are applied. There are hour limits, day limits and month limits
Hour limits. You're limited to the number of API calls you can make in a single hour. It's a 1,000 calls right now.
Day limits. Per day you can make less than or equal 10,000 calls.
Month limits. Number of calls you can do per month is defined by your subscription plan.
You will receive rate limits object in each response describing your available rate limits left.
Use Cases
There are 3 possible use cases of API covering vast majority of possible business scenarios.
Bulk segmentation w/o estimate
In this use case you submit the whole list for segmentation and as soon as segmentation is completed you retrieve results without prior estimate. The API call sequence is as follows:
Calling /audiences/segment
Receiving notification after segmentation on callbackUrl if webhook functionality is implemented.
Calling /audiences/purchase to retrieve segmentation results (subscription will be charged at this point). The method can be called as soon audience is segmented after receiving corresponding notification on callbackUrl or on schedule basis.
Bulk segmentation w/ estimate
In this use case you submit the whole list for segmentation and as soon as segmentation is completed you request price estimation for your audience before retrieving results. The API call sequence is as follows:
Calling /audiences/segment
Receiving notification after segmentation on callbackUrl if webhook is implemented.
Calling /audiences/estimate to get final price estimate before getting results. The method can be called as soon audience is segmented after receiving corresponding notification on callbackUrl or on schedule basis. The response of this method will also provide a list of accuracy/coverage options to pick from.
Calling /audiences/purchase to retrieve segmentation results with optional parameter of selected accuracy/coverage option if default coverage and accuracy doesn't satisfy your data quality thresholds. For example, you can automate your app to pick option with minimum allowed accuracy or provide your users with similar user experience as Demografy dashboard provides.
Individual prediction
In case you're building some personalization app or would like to receive demographic data only for a single person, you can call /audiences/predict
Please note that age group prediction is not available via /audiences/predict due to complexities of predicting age. All other indicators are available via /audiences/predict.
Webhook
Webhook allows you to receive real-time HTTP notifications about segmented audiences. You generally have two options:
Implement webhook and receive segmentation completed notification as soon as audience is segmented and ready for getting demographic data from (using /audiences/purchase or /audiences/estimate method to receive estimate before purchase)
Poll /audiences/purchase or /audiences/estimate method until audience is ready. You can setup reasonable interval before starting to poll - for most cases 5 minutes is fairly enough.
Webhook might be a prefered option because you're rate limited for a number of API calls (including webhook notifications) and you may do more extra calls while polling. On the other hand your webhook must be up and running to receive a notification. If webhook fails Demografy will do limited number of attempts to send a notification again.
To use webhook, you will need to set up an endpoint on a secure (HTTPS) server receiving application/json requests, then pass your publicly available webhook URL address as callbackUrl parameter of /audiences/segment method.
HTTPS
Webhook notifications are sent to secure SSL-enabled endpoints so your server must have a valid TLS/SSL certificate installed on webhook endpoint.
Authentication
Verification of notification sender is important for securing your app and preventing its abuse. For this purpose Demografy implements verification token and thin payload approaches for securing webhooks. How it works:
Verification token. Each request to your webhook will contain verificationToken property in JSON body of the request which is essentially base64 encoded sha256 hash of your public and private API key. So it's important to keep your private API key not comprimised. Below you'll find the algorithm for hashing and encoding verificationToken.
Thin payload. This approach requires nothing from your app and consists of sending only minimal information to webhook. In this case only audience's id is sent. The rest of the information you will need to obtain by subsequently calling secured REST API methods thus preventing malicious sender to send fake data that may impact your app even if the malicious send got the control over your private API key. However malicious user is still able to abuse your rate limits by provoking you to call the Demografy API with fake data so it is still highly recommended to verify verificationToken in payload and keep your private API key not comprimised.
Verification token
Verification token is generated using the following algorithm:
Your public API key is SHA256 hashed using private API key as salt by concatenating public API key + private API key as input for SHA256
Resulted hash is encoded using Base64 format
Example:
Public API key: 86131364-b90b-4967-bff9-3be60fd548e8
Private API key: a3092bc3-b5e2-4ccc-bac1-6cf6e4b46f3f
SHA256 hash: 34720ee50f8c664523ae95c50fbdd4e7142491b3ef75013bc875b69f762855c6
Encoded Base64 string: MzQ3MjBlZTUwZjhjNjY0NTIzYWU5NWM1MGZiZGQ0ZTcxNDI0OTFiM2VmNzUwMTNiYzg3NWI2OWY3NjI4NTVjNg==
In order to verify webhook request you must process your public and private API keys using the above algorithm and compare the result string with verificationToken in webhook payload.
Notification example
application/json POST body of the request containing two parameters will be sent.
verificationToken. Contains base64 encoded apiKey
audienceId. Segmented audience's id to use in subsequent /audiences/purchase and (optionally) /audiences/estimate methods.
Below is an example request:
{
  "audienceId": 1,
  "verificationToken": "c29tZXRlc3R2YWx1ZTEyMw=="  
}
Demografy expects the following response after 60 sec timeout to stop sending notifications:
{
  "isSuccess": true  
}
Notification attempts
Demografy will make extra calls if webhook fails.
First, it will make another 5 attempts immediately.
Then it will make additional 5 attempts with at least 1 minute interval between each.
And the final 5 attempts will be made with at least 1 hour interval.
There will be no more notifications for this audience if webhook is not responsing or responding incorrectly. In this case, the data will be available only via polling /audiences/purchase and (optionally) /audiences/estimate methods. Alternatively the data is always available via dashboard: API created audiences will automatically appear in dashboard.
Client SDKs
{{docsCtrl.clientList.length}} ready-to-use client SDKs are available in your API dashboard.
Get started to download SDK
Testing
Before going live you should test your API integration. For this purpose Demografy offers wide range of tools.
REST API testing
You will be able to test all REST endpoints using interactive Swagger documentation and your test API key. All methods have example requests.
Test data
To simulate different scenarios you can use the following test data:
Method
Parameter
Value
Scenario
Method
/audiences/segment
Parameter
callbackUrl
Value
<empty>
Scenario
No notification is sent to webhook
Method
/audiences/segment
Parameter
callbackUrl
Value
<your valid publicly available webhook URL>
Scenario
Notification is sent to provided webhook
Method
/audiences/segment
Parameter
callbackUrl
Value
<invalid or unreachable URL>
Scenario
Invalid webhook URL error message
Method
/audiences/segment
Parameter
callbackUrl
Value
<non-HTTPS webhook URL>
Scenario
Invalid webhook protocol error message
Method
/audiences/segment
Parameter
audience.data
Value
<empty>
Scenario
Data missing error message
Method
/audiences/segment
Parameter
audience.data
Value
<less than 100 valid entries>
Scenario
Minimum number of entries error message
Method
/audiences/segment
Parameter
audience.name
Value
<empty>
Scenario
Name is required error message
Method
/audiences/segment
Parameters
audience.typeId
Value
<invalid type id (less than 1)>
Scenario
Invalid typeId error message
Method
/audiences/segment
Parameter
audience.industryId
Value
<invalid industry id (less than 1)>
Scenario
Invalid industryId error message
Method
/audiences/estimate
Parameter
audienceId
Value
<empty or less than 1>
Scenario
Audience id missing error message
Method
/audiences/purchase
Parameter
audienceId
Value
<empty or less than 1>
Scenario
Audience id missing error message
Method
/audiences/predict
Parameter
entry
Value
<empty>
Scenario
Entry missing error message
Method
/audiences/predict
Parameter
entry.firstName
Value
<empty>
Scenario
First name is required error message
Method
/audiences/predict
Parameter
segmentOptions[].indicator
Value
2
Scenario
Invalid demographic indicator (/audiences/predict doesn't support age yet)
Please note, test data doesn't cover all possible scenarios. Please refer documentation and use production API key at the final stage of development to uncover all possible error use cases.
Webhook testing
You will be able to test webhook notifications using /audiences/segment via interactive Swagger and your localhost webhook via tools like ngrok.
Your test API key is also always available to you during further development after going live.