Authentication

All API requests require authentication using an API key. Include your API key in the request header:

TIP

You can generate your API key from your ReferralStack dashboard under Settings → Integrations. Keep your API key secure and never expose it in client-side code.

Example Request:

Error Response (Missing/Invalid API Key):

{
  "status": 401,
  "message": "Invalid API key. Please check your API key and try again."
}

Base URL

All API endpoints are relative to the base URL:

https://api.referralstack.ai/api/v1

Example Request:

HTTP Status Codes

Understanding these status codes will help you handle API responses effectively:

Status Code	Description	Common Causes
`200 OK`	Request succeeded	Successful GET, PUT, PATCH, DELETE requests
`201 Created`	Resource created successfully	Successful POST requests
`400 Bad Request`	Invalid request parameters	Missing required fields, invalid data format, validation errors
`401 Unauthorized`	Invalid or missing API key	Wrong API key, missing x-auth-referralstack header
`403 Forbidden`	Insufficient permissions	Trying to access resources outside your plan
`404 Not Found`	Resource not found	Invalid endpoint or resource ID
`422 Unprocessable Entity`	Validation error	Invalid data that fails business rules (e.g., Sequelize validation errors)
`429 Too Many Requests`	Rate limit exceeded	Too many requests in a short period
`500 Internal Server Error`	Server error	Unexpected server issue

Base URL#

HTTP Status Codes#

Base URL

HTTP Status Codes