This endpoint will allow the client to make an API call to us, passing a single WKND device ID or a list of WKND device IDs, and we return the best-matched email. This API will be behind authentication.
URL
POST [[https://api.wknd.ai/v1/identity/lookup/batch]
Request Headers
X-Client-ID: A 32-byte hashed string provided by Wunderkind.
X-Client-Secret: A 64-byte hashed string provided by Wunderkind.
Content-Type: application/json
Request and Rate Limits
Batch Size Limit: maximum of 100 device IDs can be included in a single request. If request contains more, return a 400.
Rate Limit: The API allows up to 100 device IDs to be requested per second per client. If requests exceed exceeding this rate, return a 429.
Request Body
The request must include an array of device IDs. Only device IDs are supported for lookup in this endpoint. If multiple device IDs are provided, the response will return emails for each one.
| Field | Type | Required | Description |
|---|---|---|---|
| WebsiteID | string | Yes | The website ID that the lookup will be performed for |
| DeviceIDs | array of strings | Yes | A list of WKND device IDs (at least one). Each item should be a valid deviceID. |
Success Response - 200 OK
Example:
{
"results": [
{
"device_id": "123456789",
"email": "[email protected]"
},
{
"device_id": "987654321",
"email": "[email protected]"
}
]
}Error Responses:
| HTTP Status | Description |
|---|---|
| 401 | Unauthorized – invalid or missing credentials. |
| 403 | Forbidden – authentication succeeded, but access is not permitted. |
| 429 | Rate Limited – too many requests were made in a short period of time. |
| 404 | Not Found – no identity could be resolved for the provided IDs. |
| 400 | Bad Request – missing or invalid parameters (e.g., invalid device_id, website_id). |
| 500 | Internal Server Error – unexpected issue on the server. |