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)

Or you can find it in the results when pulling the index list of affiliates.

Affiliate object

Example Affiliate:

{
  "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"
  }
}

List all Affiliates

curl "https://api.retreaver.com/api/v1/affiliates.json?api_key=[api_key]&company_id=1"

The above command returns JSON structured like this:

[
  {
    "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

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:

{
  "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

Get an Affiliate by AFID

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

Create an Affiliate

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:

{
  "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.

Error Responses

If validation fails (for example, an afid that is already in use), the API returns a 500 with an errors object:

{
  "affiliate": {
    "errors": {
      "afid": ["has already been taken"]
    }
  }
}

Update an Affiliate

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:

{
  "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.

Delete an Affiliate

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]:

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"}}'