API Reference

This document provides detailed information about Endorsely's API endpoints, request formats, and response structures.

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_SECRET

Endpoints

Track Referral

Records a conversion from an affiliate referral. This endpoint can be used for both paid conversions and free signups (leads).

POST https://app.endorsely.com/api/public/refer

Request Parameters

Parameter	Type	Required	Description
referralId	string	Yes	The unique referral ID captured from window.endorsely_referral
organizationId	string	Yes	Your Endorsely organization ID
email	string	No	Email address of the referred user
amount	number	No	Payment amount in cents (e.g., $10.00 = 1000)
name	string	No	Name of the referred user
customerId	string	No	Your internal customer ID for the referred user
status	string	No	For free signups, use "Signed Up"

Example Request

// For a paid conversion
{
  "referralId": "ref_abc123",
  "organizationId": "<your-organization-id>",
  "email": "[email protected]",
  "amount": 5000,
  "name": "John Doe",
  "customerId": "cust_12345"
}

// For a free signup (lead)
{
  "referralId": "ref_abc123",
  "organizationId": "<your-organization-id>",
  "email": "[email protected]",
  "status": "Signed Up"
}

Response

{
  "success": true,
  "data": {
    "id": "conv_12345",
    "referralId": "ref_abc123",
    "amount": 5000,
    "commission": 500,
    "status": "processed"
  }
}

Error Handling

The API returns appropriate HTTP status codes for different error scenarios:

• 400 Bad Request: Missing required parameters or invalid data
• 401 Unauthorized: Invalid API key
• 404 Not Found: Referral ID not found
• 500 Internal Server Error: Server-side issue

Error responses include a message explaining what went wrong:

{
  "success": false,
  "error": "Invalid referral ID provided"
}

Rate Limits

The API is rate-limited to 100 requests per minute per organization. If you exceed this limit, you'll receive a 429 Too Many Requests response.