# Affiliates API Affiliates allow you to attribute calls back to the source that generated them, and to sync with any external tracking systems you use. If you're not in affiliate marketing, Affiliate objects can be used for whatever source attribution is relevant, they exist purely for your reference. Every Affiliate has an `afid`, which is your own external identifier for the affiliate. If you don't supply one when creating an affiliate, Retreaver will auto-generate one for you. In addition to the `afid`, each affiliate has a Retreaver-assigned internal `id` that you can also use to look it up. ## Where to find AFID AFID is user-customizable ID which references an Affiliate. It can be found on every publisher (source) page under "Publisher ID" (Source ID) ![](/media/a8/a8dd2eeb311dbfa74068119cbdc5500fa7e65c5652c6ef608e241c0c52a0db71.png) Or you can find it in the results when pulling the index list of affiliates. ## Affiliate object > Example Affiliate: ```json { "affiliate": { "id": 1, "afid": "0002", "first_name": "Nancy", "last_name": "Drew", "company_name": "Acme", "alternative_id": null, "created_at": "2012-05-03T15:56:01Z", "updated_at": "2012-05-03T15:56:01Z" } } ``` | Field | Type | Description | | ---------------- | ----------------- | --------------------------------------------------------------------------- | | `id` | integer | Retreaver's internal ID for the affiliate. | | `afid` | string | Your external ID for the affiliate. Auto-generated if not provided on create. | | `first_name` | string \| null | The affiliate's first name. | | `last_name` | string \| null | The affiliate's last name. | | `company_name` | string \| null | The affiliate's company name. | | `alternative_id` | string \| null | An additional external identifier. | | `created_at` | string (ISO 8601) | When the affiliate was created. | | `updated_at` | string (ISO 8601) | When the affiliate was last updated. | ## List all Affiliates ```shell curl "https://api.retreaver.com/api/v1/affiliates.json?api_key=[api_key]&company_id=1" ``` > The above command returns JSON structured like this: ```json [ { "affiliate": { "id": 1, "afid": "0002", "first_name": "Nancy", "last_name": "Drew", "company_name": "Acme", "alternative_id": null, "object_key": "a1b2c3d4", "created_at": "2012-05-03T15:56:01Z", "updated_at": "2012-05-03T15:56:01Z" } } ] ``` Returns all Affiliates for the authenticated Company. Results are paginated — use the `page` (default `1`) and `per_page` (default `25`, max `100`) query parameters. ### HTTP Request `GET https://api.retreaver.com/api/v1/affiliates.json?api_key=[api_key]&company_id=1` ## Get a specific Affiliate ```shell curl "https://api.retreaver.com/api/v1/affiliates/1.json?api_key=[api_key]&company_id=1" ``` > The above command returns JSON structured like this: ```json { "affiliate": { "id": 1, "afid": "0002", "first_name": "Nancy", "last_name": "Drew", "company_name": "Acme", "alternative_id": null, "created_at": "2012-05-03T15:56:01Z", "updated_at": "2012-05-03T15:56:01Z" } } ``` Returns a single Affiliate by its Retreaver internal ID. ### HTTP Request `GET https://api.retreaver.com/api/v1/affiliates/{id}.json?api_key=[api_key]&company_id=1` ### Path Parameters | Parameter | Type | Description | | --------- | ------- | ---------------------------------------- | | `id` | integer | The Retreaver internal ID of the affiliate. | ## Get an Affiliate by AFID ```shell curl "https://api.retreaver.com/affiliates/afid/0002.json?api_key=[api_key]&company_id=1" ``` Finds an Affiliate using your external `afid` instead of the Retreaver internal ID. ### HTTP Request `GET https://api.retreaver.com/affiliates/afid/{client_afid}.json?api_key=[api_key]&company_id=1` ### Path Parameters | Parameter | Type | Description | | ------------- | ------ | ----------------------------------- | | `client_afid` | string | Your external AFID for the affiliate. | ## Create an Affiliate ```shell curl -s \ -X POST \ "https://api.retreaver.com/api/v1/affiliates.json?api_key=[api_key]&company_id=1" \ -H "Content-Type: application/json" \ -d '{"affiliate":{"afid":"0002","first_name":"Nancy","last_name":"Drew"}}' ``` > The above command returns JSON structured like this: ```json { "affiliate": { "id": 1, "afid": "0002", "first_name": "Nancy", "last_name": "Drew", "company_name": null, "alternative_id": null, "created_at": "2025-01-28T12:18:44.131Z", "updated_at": "2025-01-28T12:18:44.131Z" } } ``` Creates a new Affiliate. If the `afid` is omitted, Retreaver will auto-generate one. ### HTTP Request `POST https://api.retreaver.com/api/v1/affiliates.json?api_key=[api_key]&company_id=1` `Content-Type: application/json` ### Body Parameters All parameters must be nested under an `affiliate` key. | Parameter | Type | Default | Required | Description | | ---------------- | ------- | ------- | -------- | --------------------------------------------------------------------------------- | | `afid` | string | | | Your external ID for this affiliate. Auto-generated if blank. | | `first_name` | string | null | | The affiliate's first name. | | `last_name` | string | null | | The affiliate's last name. | | `company_name` | string | null | | The affiliate's company name. | | `alternative_id` | string | null | | An additional external identifier. | | `paused` | boolean | false | | Paused affiliates are excluded from active routing. | ### Error Responses If validation fails (for example, an `afid` that is already in use), the API returns a `500` with an errors object: ```json { "affiliate": { "errors": { "afid": ["has already been taken"] } } } ``` ## Update an Affiliate ```shell curl -s \ -X PUT \ "https://api.retreaver.com/api/v1/affiliates/1.json?api_key=[api_key]&company_id=1" \ -H "Content-Type: application/json" \ -d '{"affiliate":{"first_name":"Nathan"}}' ``` > The above command returns JSON structured like this: ```json { "affiliate": { "id": 1, "afid": "0002", "first_name": "Nathan", "last_name": "Drew", "company_name": null, "alternative_id": null, "created_at": "2012-05-03T14:29:37Z", "updated_at": "2012-05-03T20:20:03Z" } } ``` Updates any attributes on the Affiliate. Only the fields you pass are changed — omitted fields remain untouched. You can identify the affiliate by either its Retreaver internal `id` or your external `afid`. ### HTTP Request `PUT https://api.retreaver.com/api/v1/affiliates/{id}.json?api_key=[api_key]&company_id=1` `PUT https://api.retreaver.com/affiliates/afid/{client_afid}.json?api_key=[api_key]&company_id=1` ### Body Parameters Accepts the same parameters as [Create an Affiliate](#create-an-affiliate). > [!TIP] > To pause an affiliate so it is excluded from active routing, send `{"affiliate":{"paused":true}}`. ## Delete an Affiliate ```shell curl -X DELETE "https://api.retreaver.com/api/v1/affiliates/1.json?api_key=[api_key]&company_id=1" ``` Deletes the given Affiliate. You can identify it by either its Retreaver internal `id` or your external `afid`. ### HTTP Request `DELETE https://api.retreaver.com/api/v1/affiliates/{id}.json?api_key=[api_key]&company_id=1` `DELETE https://api.retreaver.com/affiliates/afid/{client_afid}.json?api_key=[api_key]&company_id=1` ### Deleting Affiliates with Associated Numbers If the Affiliate has Numbers attached, the request will fail unless you specify what to do with them via `affiliate[destroy_behavior]`: | Value | Behavior | | -------- | --------------------------------------------------------------- | | `delete` | Permanently delete all Numbers associated with the affiliate. | | `keep` | Keep the Numbers but remove the affiliate association (orphan them). | ```shell curl -X DELETE \ "https://api.retreaver.com/api/v1/affiliates/1.json?api_key=[api_key]&company_id=1" \ -H "Content-Type: application/json" \ -d '{"affiliate":{"destroy_behavior":"keep"}}' ``` > [!NOTE] > Affiliates with attached Number Pools cannot be deleted. Remove the Number Pools first and retry.