Docs menu
Referrals API endpoint
Capture a referral click
Records sanitized referral click metadata for attribution analytics.
/referrals/clickOverview
Records sanitized referral click metadata for attribution analytics.
Request schema
| Name | In | Type | Required | Enum | Example | Description |
|---|---|---|---|---|---|---|
| request | body | object | Yes | Referral click metadata |
Authentication
This endpoint does not require authentication.
Billing
Endpoint usage is metered in credits. The plan prices, included credits, limits, and overage rates below match the active backend billing configuration.
- Credit cost
- 1 credit/request
- Charged response
- Successful 2xx responses
| Plan | Price | Included credits | Daily cap | Rate limit | Overage |
|---|---|---|---|---|---|
| Free | $0/mo | 2,000 | 500 daily credits | 5/min | No overage |
| Starter | $9/mo | 20,000 | 5,000 daily credits | 15/min | $0.75/1,000 overage credits when enabled |
| Growth | $29/mo | 100,000 | 25,000 daily credits | 45/min | $0.45/1,000 overage credits when enabled |
| Pro | $79/mo | 400,000 | No daily cap | 120/min | $0.30/1,000 overage credits |
| Business | $199/mo | 1,200,000 | No daily cap | 300/min | $0.20/1,000 overage credits |
| Enterprise | $499/mo | 5,000,000 | No daily cap | 1,000/min | $0.12/1,000 overage credits |
Infrastructure behavior
This endpoint is executed through Crawlora's managed scraping infrastructure.
- Proxy strategy: managed automatically where needed
- Browser rendering: enabled for supported targets that require rendered HTML or JavaScript execution
- Browser cluster: supported dynamic workloads can be routed through distributed browser instances
- Retry behavior: automatic retry/fallback may be used depending on endpoint type
- Challenge handling: challenged pages or unusable upstream HTML are detected and surfaced clearly when they cannot be used
- Billing: credits are charged only for successful 2xx responses
- Observability: responses include request context where available
Response behavior
- Stores hashed IP and user-agent values for abuse detection. - Returns the click id that should be kept in the referral click cookie. - Invalid referral codes return the standard invalid params envelope.
Error behavior
Crawlora does not silently return bad data when the upstream page cannot be used.
| Status | Common failure case |
|---|---|
| 400 | Invalid input or missing required parameter |
| 429 | Plan or endpoint rate limit exceeded |
| 500 | Internal execution error |
| 502 | Upstream platform failed, returned unusable HTML, or served a challenge page that could not be resolved |
When possible, Crawlora returns structured error context so your integration can retry, back off, or inspect the request.
Failure responses
| Status | Description | Schema |
|---|---|---|
| 400 | Invalid request | #/definitions/app.Response |
| 500 | Internal server error | #/definitions/app.Response |
Request body example
{
"click_id": "refclk_abc123",
"code": "A1B2C3D4E5F6",
"landing_path": "/pricing",
"utm_campaign": "spring-launch",
"utm_medium": "email",
"utm_source": "newsletter"
}Example response
{
"code": 200,
"msg": "ok",
"data": {
"click_id": "refclk_abc123",
"code": "A1B2C3D4E5F6"
}
}Request schema
#/definitions/referrals.referralClickRequestDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| click_id | string | No | refclk_abc123 | |||
| code | string | No | A1B2C3D4E5F6 | |||
| landing_path | string | No | /pricing | |||
| utm_campaign | string | No | spring-launch | |||
| utm_medium | string | No | ||||
| utm_source | string | No | newsletter |
Response schema
#/definitions/referrals.referralClickResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| click_id | string | No | refclk_abc123 | |||
| code | string | No | A1B2C3D4E5F6 |
Code examples
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X POST "https://api.crawlora.net/api/v1/referrals/click" \
-H "Content-Type: application/json" \
-d '{"click_id":"refclk_abc123","code":"A1B2C3D4E5F6","landing_path":"/pricing","utm_campaign":"spring-launch","utm_medium":"email","utm_source":"newsletter"}'Responsible public web data workflows
Crawlora is designed for responsible structured public web data workflows. Customers are responsible for using Crawlora in compliance with applicable laws, third-party rights, target-platform rules, and Crawlora terms.
Read Crawlora terms