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

Need an API key? See our guide on Getting Your Endorsely API Key for step-by-step instructions.

Endpoints

Get Affiliate Information

Retrieves affiliate information and associated promotion codes for a specific referral code.

GET https://app.endorsely.com/api/public/{organizationId}/affiliate/{referralCode}

Path Parameters

Parameter	Type	Required	Description
organizationId	string	Yes	Your Endorsely organization ID
referralCode	string	Yes	The referral code to look up

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token with your API key

Example Request

import requests

ENDORSELY_API_KEY = "your_api_key_here"
ENDORSELY_ORGANIZATION_ID = "your_organization_id_here"
REFERRAL_CODE = "example_referral_code"

response = requests.get(
    f"https://app.endorsely.com/api/public/{ENDORSELY_ORGANIZATION_ID}/affiliate/{REFERRAL_CODE}",
    headers={"Authorization": f"Bearer {ENDORSELY_API_KEY}"}
)

data = response.json()

Response

{
  "affiliateId": "aff_12345678-1234-1234-1234-123456789abc",
  "promotionCodes": [
    {
      "code": "SAVE10",
      "stripePromotionCodeId": "promo_example123456789",
      "isActive": true
    }
  ]
}

Response Fields

Field	Type	Description
affiliateId	string	Unique identifier for the affiliate
promotionCodes	array	List of promotion codes associated with the affiliate
promotionCodes[].code	string	The promotion code (e.g., "SAVE10")
promotionCodes[].stripePromotionCodeId	string	Stripe promotion code ID for integration
promotionCodes[].isActive	boolean	Whether the promotion code is currently active

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.