BrokerGrid Partner API

Send Leads to a BrokerGrid CRM and follow what happens to them.

Authentication

The broker gives you an API key. Send it as a Bearer token on every request, over HTTPS, to https://partner-api-demo.brokergrid.net/v1:

Authorization: Bearer bgp_XXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Accept: application/json

Keep the key secret. When the broker rotates it, the previous key keeps working for 24 hours. The broker may also restrict your key to IP addresses and to a number of requests per minute.

Send a Lead

POST /v1/leads · scope leads.create

Field	Rules
`campaign`	Campaign code. Optional when your key has a single Campaign.
`first_name`, `last_name`	Required, up to 255 characters.
`email`	Required unless `phone` is given.
`phone`	International format, such as `+4930123456`. Required unless `email` is given.
`country`	ISO 3166-1 alpha-2 code, such as `DE`.
`language`	Language code, such as `en`.
`company`, `description`	Optional.
`tracking`	Object of the tracking parameters the Campaign captures (click ids, sub ids). See Campaigns.

curl -X POST https://partner-api-demo.brokergrid.net/v1/leads \
  -H "Authorization: Bearer $BROKERGRID_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"campaign": "AFF-1", "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com",
       "phone": "+4930123456", "country": "DE", "tracking": {"click_id": "c-123"}}'

The answer is 201 Created with the Lead. When the CRM already knew this person, the Lead is still stored and duplicate is true, with the matching fields in duplicate_fields.

{
  "data": {
    "id": 4182,
    "campaign": "AFF-1",
    "status": "open",
    "duplicate": false,
    "duplicate_fields": [],
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com",
    "phone": "+4930123456",
    "country": "DE",
    "language": null,
    "company": null,
    "tracking": {"click_id": "c-123"},
    "converted_at": null,
    "created_at": "2026-10-23T10:15:00+00:00"
  }
}

Read Leads

You can read only the Leads your key sent. Scope leads.read.

GET `/v1/leads`

Parameter	Rules
`campaign`	Campaign code.
`created_from`, `created_to`	Dates or ISO 8601 timestamps.
`per_page`	1 to 100, default 25. Follow `links.next` for the next page.

GET `/v1/leads/{id}`

status is open, converted (the Lead became a customer; see converted_at) or lost.

Campaigns

GET /v1/campaigns lists the Campaigns your key can send Leads to, with the countries each refuses and the tracking parameters it captures.

{
  "data": [
    {
      "code": "AFF-1",
      "name": "Spring affiliates",
      "active": true,
      "brand": "Acme Markets",
      "restricted_countries": ["US"],
      "tracking_parameters": [{"name": "click_id", "label": "Click ID"}]
    }
  ]
}

Errors

Status	Meaning
`401`	The API key is missing, wrong, revoked or expired, or its API User is disabled.
`403`	The request came from an IP address the key does not allow, or the key lacks the scope.
`404`	No such Lead among the ones your key sent.
`422`	The Lead was refused. `errors` names each field and why.
`429`	Too many requests. Wait for the seconds in the `Retry-After` header.

{
  "message": "This Campaign does not accept Leads from this country.",
  "errors": {"country": ["This Campaign does not accept Leads from this country."]}
}