Partner API Key
All Partner API requests require a Partner API Key passed in the request header.
X-Partner-Key: pk_live_abc123def456...
Authorization: Bearer pk_live_abc123def456...
Getting a Partner API Key
Partner API keys are provisioned during onboarding. Contact your Recover account manager or email [email protected]. Each key is scoped to your partner account and grants access to all sub-accounts under it.
Keys follow the format pk_live_ followed by 32 characters. Keep your key secret — it grants full access to create and manage accounts, import leads, and generate embed tokens.
Never expose your Partner API key in client-side code. All API calls should be made from your backend server.
Key Rotation
To rotate a key, contact your account manager. The old key will remain valid for 24 hours after the new key is issued.
Rate Limits
| Endpoint | Limit |
|---|
| Account creation | 100 / hour |
| Lead import (single) | 1,000 / minute |
| Lead import (bulk) | 50 / minute |
| Embed token generation | 500 / hour |
| Conversation reads | 5,000 / minute |
| Message sends | 100 / minute per account |
| All other endpoints | 1,000 / minute |
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1771200000
429 Too Many Requests with a Retry-After header.
All errors follow a consistent format:
{
"error": {
"code": "unauthorized",
"message": "Invalid or missing Partner API key",
"status": 401
}
}
Error Codes
| Code | Status | Description |
|---|
unauthorized | 401 | Invalid or missing Partner API key |
forbidden | 403 | Key does not have access to this resource |
not_found | 404 | Account, lead, or resource not found |
invalid_phone | 400 | Phone number format is invalid |
duplicate_lead | 409 | Lead with this external_id already exists |
account_deactivated | 403 | Account has been deactivated |
token_expired | 401 | Embed token has expired |
rate_limited | 429 | Too many requests |
validation_error | 422 | Request body failed validation |
internal_error | 500 | Internal server error |
