DocumentationAPI Reference

Lead Conversions

The Lead Conversions API provides a simple interface to manage lead conversions. The API allows you to create or read your lead conversions.

JSON format

AttribueRead OnlyTypeDescription
idtruenumberUnique identifier of the lead conversion.
lead_idtruenumberUnique identifier of the converted lead.
individual_idtruenumberUnique identifier of the individual created as a result of the conversion.
organization_idtruenumberUnique identifier of the organization created as a result of the conversion.
deal_idtruenumberUnique identifier of the deal created as a result of the conversion.
creator_idtruenumberUnique identifier of the user who converted the lead.
created_attruestringDate and time of the creation in UTC (ISO8601 format).

Retrieve all lead conversions

GET /v2/lead_conversions

Returns all lead conversions available to the user according to the provided parameters. Records are sorted in descending order by lead conversion ID. They can be paginated by page or cursor param. The usage of the page param is limited up to number 50. In order to fetch further records you should use cursor param. A link with specified cursor is provided in the response under meta section as next_page. The link is always present if only there are subsequent records available.

It is possible to retrieve specific conversion by ID of the converted lead or by IDs of the created objects by providing one of the parameters: lead_id, individual_id, organization_id or deal_id.

Parameters

NameRequiredTypeInDescription
pagefalsenumberQueryPage number to start from. Page numbering starts at 1 and omitting the page parameter will result in returning the first page. The maximum requested page can be 50.
per_pagefalsenumberQueryNumber of records to return on one page. The default limit is 25 and the maximum size of page is 200.
cursorfalsestringQueryPagination token for an iteration over the records. It allows for fetching a set of subsequent data.
lead_idfalsenumberQueryUnique identifier of the lead that has been converted.
individual_idfalsenumberQueryUnique identifier of the contact (individual) created as a result of the conversion.
organization_idfalsenumberQueryUnique identifier of the contact (organization) created as a result of the conversion.
deal_idfalsenumberQueryUnique identifier of the deal created as a result of the conversion.
creator_idfalsenumberQueryUnique identifier of the user who converted the lead.

Allowed for

  • Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/lead_conversions \-H "Accept: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
    {      "items": [{        "data": {          "id": 2,          "lead_id": 2,          "individual_id": 4,          "organization_id": 5,          "deal_id": 5,          "creator_id": 1,          "created_at": "2021-02-17T16:32:56Z"        },        "meta": {          "type": "lead_conversion",          "links": {            "individual": "https://api.getbase.com/v2/contacts/4",            "organization": "https://api.getbase.com/v2/contacts/5",            "deal": "https://api.getbase.com/v2/deals/5"          }        }      },      {        "data": {          "id": 1,          "lead_id": 1,          "individual_id": 3,          "organization_id": null,          "deal_id": null,          "creator_id": 2,          "created_at": "2021-02-17T16:32:57Z"        },        "meta": {          "type": "lead_conversion",          "links": {            "individual": "https://api.getbase.com/v2/contacts/3",            "organization": null,            "deal": null          }        }      }],      "meta": {        "type": "collection",        "count": 2,        "links": {          "next_page": "https://api.getbase.com/v2/lead_conversions?cursor=eyJsYXN0X2lkIjo2NTA3ODF9%0A&per_page=25"        }      }    }

Create a lead conversion

POST /v2/lead_conversions

Converts a lead to an individual and/or an organization and/or a deal and returns created lead conversion record. After successful conversion all activities associated with the converted lead are attached to newly created contacts and/or deal asynchronously with minimal delay.

The lead conversion is about converting a lead into a contact and - optionally - creating a deal for the created contacts. Lead can be converted to an individual or an organization or both. Possible scenarios:

  1. If a lead has specified last_name, an individual is created as a result of the conversion.
  2. If a lead has specified organization_name, an organization is created as a result of the conversion.
  3. If both last_name and organization_name fields are specified, lead will be converted to an individual and an organization.

Parameters

NameRequiredTypeInDescription
lead_idtruenumberBodyUnique identifier of the lead that is going to be converted.
owner_idfalsenumberBodyUnique identifier of the user that will be set as an owner of all objects created during conversion. If not provided, all these objects will be owned by the current lead's owner.
create_dealfalsebooleanBodyIndicates whether a deal should be created as a result of the conversion. Default is true.

Allowed for

  • Agents

Using cURL

curl -v -X POST https://api.getbase.com/v2/lead_conversions \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "lead_id": 2,    "owner_id": 7,    "create_deal": false  }}'

Example response

Content-Type: application/json; charset=utf-8         Content-Language: en    {      "data": {        "id": 1,        "lead_id": 2,        "individual_id": 3,        "organization_id": 4,        "deal_id": null,        "creator_id": 1,        "created_at": "2021-02-17T16:32:56Z"      },      "meta": {        "type": "lead_conversion",        "links": {          "individual": "https://api.getbase.com/v2/contacts/3",          "organization": "https://api.getbase.com/v2/contacts/4",          "deal": null        }      }    }