Brokerkit API

Creating and updating recruiting/retention contacts in Brokerkit

General Information

Using the API

If you are using the Zapier webhooks app to access our API, please see the details here. However, this article could still be valuable as a reference on the parameters available to use in your webhook and how to format them.
Finding API key for an Account
- Click this link while logged into your Brokerkit account, or visit the “Account Settings” section of your Brokerkit account, then click the “Copy to Clipboard” button to copy your API Key for your Team.

API URL

The API URL is https://api.getbrokerkit.com/v2, and all the request URLs must be appended to

this URL.

For example, to create a "lead," make a POST request to https://api.getbrokerkit.com/v2/leads.

Request Headers

With every request, you must set the following Authorization and Content-Type headers:

Authorization: Token token=YOUR API KEY
Content-Type: application/json

Response Codes

Response Code	Returned when
200 OK	Successful GET request
201 Created	The resource has been successfully created
204 No Content	The resource has been successfully updated
400 Bad Request	The request is erroneous (e.g., a required parameter was not provided)
401 Unauthorised	Failed API authorization
403 Forbidden	No access to a resource (e.g., makes a lead create request but has no create lead permission)
404 Not Found	The requested resource was not found
422 Unprocessable Entity	The request was valid but failed because of validation errors (e.g., the request tried to create a new user with an email that already exists)

Things to keep in mind:

When a parameter is required, it is marked as "REQUIRED FIELD." All other fields are optional.
Request parameters must be encoded in UTF-8.
API Testing

- If you include the test parameter with the boolean value "true," the API will not save the lead to the DB and notify users subscribed to new lead notifications, but if the value is set to "false," the API will save the lead to the DB and notify users subscribed to new lead notifications
- If the test parameter is set to true: "test: true":
  - In the request parameters, the email will not be populated in the response, and the response will have `"email": null.`
- An email will be populated as expected once the test is set to false or removed from parameters.
Updating duplicate records
- We have implemented a system for detecting duplicate records.
- Duplicate matches occur on two fields:
  - 1) Records will match on any "email" addresses
  - 2) Or records will match on any "agent_id."
- If there are duplicate records:
  - It will update the records found with data from the new contact.
  - If there is no duplicate record, It will create a new record.

Creating/Updating Contacts

	Value
URL	/leads
Method	POST
Response	Lead or error list

Example Parameters:

Parameter Name	Example	The field name in the user interface	Comment
test	false	N/A	IT SHOULD BE A BOOLEAN VALUE, NOT A STRING. If you include the test(true) parameter, the API will not save the lead to the DB and notify.
product	retention	N/A	When this parameter is used, an agent in retention will be created vs. a lead in recruiting.
first_name	Peet	Full Name
last_name	Peeter	Full Name
birthday	24/03/1975	Birthday
phone	+11111111111	Cell Phone	Should be a valid phone number
other_phone	+11111111111	Other Phone	Should be a valid phone number
office_phone	+11111111111	Office Phone	Should be a valid phone number
email	peet@example.com	Email (Main)
agent_id	a68d4b23	Agent ID
bucket	default	Normal/Archived	Should be "default", "backlog," or "archived"
status	new_lead	Status	Should be "new_lead", "contact_attempt", "contact_made", "appt_set", "needs_evaluated", "onboarding", "active"
note	#NOTE	Referrer Notes
source	Abstrakt	Source	The value must be an out-of-the-box source or added as a Custom Source to be found in the source filter dropdown
currently_at	RE-MAX United	Company Name
alt_address	1111 A Shangri, New York, NY 11111, USA	Home address
alt_city	New York	Home City
alt_state	NY	Home State
alt_zip	11111	Home zip
office_address	1111 N Tatum, New York, NY 11111, USA	Office address
office_city	New York	Office city
office_state	NY	Office state
office_zip	11111	Office zip
kpa_taken	true	Personality Assessment Taken
active_listings_count	111	Active Listing
production_ytd	10000	Total $ Production LTM
rating	4	Rating	An integer from 4 to 10
production_label	mega	Production Label	Should be "mega", "super", "mid", "low", "new", "in_school", or "not_licensed"!!! otherwise, you will get an error.
owner_email	test@getbrokerkit.com	Owner	The owner_email is the email address of the team member at BrokerKit (Admin / Staff). Please ensure that the owner(user with email = owner_email) exists in the BK app before creating leads with an owner.
referrer_email	test@getbrokerkit.com	Referrer	The referrer email is the team member's email address at BrokerKit (Admin / Staff users only). Please ensure that the referrer(user with email = referrer_email) exists in the BK app before creating leads with a referrer.
resume_url	https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf	Resume	Value refers to an URL that contains a contact's resume in PDF format The file should be public
document_urls	https://morth.nic.in/sites/default/files/dd12-13_0.pdf	Documents	Value refers to an URL that can contain these supported file types: PDF Image (PNG, JPG, JPEG) MS Word (DOC, DOCX) MS Excel (XLS, XLSX) PowerPoint (PPT, PPTX) Plain Text (.txt) (can be uploaded but can not be displayed in the BK UI) Rich Text Format (.rtf) (can be uploaded but can not be displayed in the BK UI) CSV (can be uploaded but can not be displayed in the BK UI) The file should be public

Example request(cURL):

Just copy and paste this code into your console and run.

Recruiting Lead Example:

curl -X POST \
 https://api.getbrokerkit.com/v2/leads \
 -H 'Authorization: Token token=Your Team Token' \
 -H 'Content-Type: application/json' \
 -d '{
 "test": false,
 "first_name": "Peet",
 "last_name": "Peeter",
 "birthday": "24/03/1975",
 "phone": "+11111111111",
 "email": "peet@example.com",
 "agent_id": "a68d4b23",
 "bucket": "default",                              
 "status": "new_lead",  
 "note": "#NOTE",
 "source": "Abstrakt",
 "currently_at": "RE-MAX United",
 "alt_address": "1111 A Shangri, New York, NY 11111, USA",
 "alt_city": "New York",
 "alt_state": "NY",
 "alt_zip": "1111",
 "office_address": "1111 N Tatum, New York, NY 11111, USA",
 "office_city": "New York",
 "office_state": "NY",
 "office_zip": "11111",
 "kpa_taken": "true",
 "active_listings_count": "111",
 "rating": "4",
 "production_ytd": "10000",
 "production_label": "mega",
 "owner_email": "test@brokerkit.com",
 "referrer_email": "test@brokerkit.com",
 "other_phone": "+11111111111",
 "office_phone": "+11111111111"
 "resume_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
 "document_urls": [
         "https://morth.nic.in/sites/default/files/dd12-13_0.pdf"
 ]
}'

Example of successful response:

{
    "id": ID,
    "team_id": TEAM_ID,
    "status": "new_lead",
    "bucket": "default",
    "photo_url": null,
    "first_name": "Peet",
    "last_name": "Peeter",
    "name": "Peet Peeter",
    "birthday": "1975-03-24",
    "email": "peet@example.com",
    "phone": "+12025550166",
    "production_label": "mega",
    "production_ytd": 10000,
    "currently_at": "RE-MAX United",
    "source": "Abstrakt",
    "rating": 4,
    "kpa_taken": true,
    "active_listings_count": "111",
    "referred_at": "2022-05-05",
    "anniversary_month": null,
    "joined_at": null,
    "last_activity_at": "2022-05-04T22:46:15.506Z",
    "first_appointment_at": null,
    "last_appointment_at": null,
    "updated_at": "2022-05-04T22:46:17.052Z",
    "created_at": "2022-05-04T22:46:17.052Z",
    "note": "#NOTE",
    "links": {},
    "alt_address": "1111 A Shangri, New York, NY 11111, USA",
    "alt_city": "New York",
    "alt_state": "New York",
    "alt_zip": "10473",
    "alt_lat": 40.809102,
    "alt_lng": -73.857723,
    "office_address": "1111 A Shangri, New York, NY 11111, USA",
    "office_city": "New York",
    "office_state": "New York",
    "office_zip": "10473",
    "office_lat": 40.809102,
    "office_lng": -73.857723,
    "office_phone": "+12025550166",
    "other_phone": "+12025550166",
    "agent_id": "a68d4b23",
    "recruiting": true,
    "retention": false,
    "archived": false,
    "backlogged": false,
    "owner": {
        "id": ID,
        "email": "test@getbrokerkit.com",
        "title": "Mr",
        "first_name": "Test",
        "last_name": "Brokerkit",
        "name": "Test Brokerkit",
        "avatar_url": "URL",
        "admin": true,
        "signature": "",
        "timezone": "America/Halifax",
        "phone": "",
        "last_sign_in_at": "2021-09-01T15:45:50.456Z",
        "updated_at": "2022-05-04T22:41:15.295Z",
        "created_at": "2019-10-04T10:06:25.581Z",
        "avatar": {
            "medium": "URL",
            "small": "URL",
            "tiny": "URL"
        }
    },
    "referrer": {
        "id": ID,
        "email": "test@getbrokerkit.com",
        "title": "Mr",
        "first_name": "Test",
        "last_name": "Brokerkit",
        "name": "Test Brokerkit",
        "avatar_url": "URL",
        "admin": true,
        "signature": "",
        "timezone": "America/Halifax",
        "phone": "",
        "last_sign_in_at": "2021-09-01T15:45:50.456Z",
        "updated_at": "2022-05-04T22:41:15.295Z",
        "created_at": "2019-10-04T10:06:25.581Z",
        "avatar": {
            "medium": "URL",
            "small": "URL",
            "tiny": "URL"
        }
    }
}

Retention Agent Example:

curl -X POST \
 https://api.getbrokerkit.com/v2/leads \
 -H 'Authorization: Token token=Your Team Token' \
 -H 'Content-Type: application/json' \
 -d '{
 "test": false,
 "product": "retention",
 "first_name": "Peet",
 "last_name": "Peeter",
 "birthday": "24/03/1975",
 "phone": "+11111111111",
 "email": "peet@example.com",
 "agent_id": "a68d4b23",
 "bucket": "default",                              
 "status": "onboarding",  
 "note": "#NOTE",
 "source": "Abstrakt",
 "currently_at": "RE-MAX United",
 "alt_address": "1111 A Shangri, New York, NY 11111, USA",
 "alt_city": "New York",
 "alt_state": "NY",
 "alt_zip": "1111",
 "office_address": "1111 N Tatum, New York, NY 11111, USA",
 "office_city": "New York",
 "office_state": "NY",
 "office_zip": "11111",
 "kpa_taken": "true",
 "active_listings_count": "111",
 "rating": "4",
 "production_ytd": "10000",
 "production_label": "mega",
 "owner_email": "test@brokerkit.com",
 "referrer_email": "test@brokerkit.com",
 "other_phone": "+11111111111",
 "office_phone": "+11111111111"
 "resume_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
 "document_urls": [
         "https://morth.nic.in/sites/default/files/dd12-13_0.pdf"
 ]
}'

Example of successful response:

{
    "id": ID,
    "team_id": TEAM ID,
    "status": "onboarding",
    "bucket": "default",
    "photo_url": null,
    "first_name": "Peet",
    "last_name": "Peeter",
    "name": "Peet Peeter",
    "birthday": "1975-03-24",
    "email": "peet@example.com",
    "phone": "+12025550166",
    "production_label": "mega",
    "production_ytd": 10000,
    "currently_at": "RE-MAX United",
    "source": "Abstrakt",
    "rating": 4,
    "kpa_taken": true,
    "active_listings_count": "111",
    "referred_at": "2022-05-05",
    "anniversary_month": null,
    "joined_at": null,
    "last_activity_at": "2022-05-04T23:05:49.014Z",
    "first_appointment_at": null,
    "last_appointment_at": null,
    "updated_at": "2022-05-04T23:05:49.707Z",
    "created_at": "2022-05-04T23:05:49.707Z",
    "note": "#NOTE",
    "links": {},
    "alt_address": "1111 A Shangri, New York, NY 11111, USA",
    "alt_city": "New York",
    "alt_state": "New York",
    "alt_zip": "10473",
    "alt_lat": 40.809102,
    "alt_lng": -73.857723,
    "office_address": "1111 A Shangri, New York, NY 11111, USA",
    "office_city": "New York",
    "office_state": "New York",
    "office_zip": "10473",
    "office_lat": 40.809102,
    "office_lng": -73.857723,
    "office_phone": "+12025550166",
    "other_phone": "+12025550166",
    "agent_id": "a68d4b23",
    "recruiting": false,
    "retention": true,
    "archived": false,
    "backlogged": false,
    "owner": {
        "id": ID,
        "email": "test@getbrokerkit.com",
        "title": "Mr",
        "first_name": "Test",
        "last_name": "Brokerkit",
        "name": "Test Brokerkit",
        "avatar_url": "URL",
        "admin": true,
        "signature": "",
        "timezone": "America/Halifax",
        "phone": "",
        "last_sign_in_at": "2021-09-01T15:45:50.456Z",
        "updated_at": "2022-05-04T22:41:15.295Z",
        "created_at": "2019-10-04T10:06:25.581Z",
        "avatar": {
            "medium": "URL",
            "small": "URL",
            "tiny": "URL"
        }
    },
    "referrer": {
        "id": ID,
        "email": "test@getbrokerkit.com",
        "title": "Mr",
        "first_name": "Test",
        "last_name": "Brokerkit",
        "name": "Test Brokerkit",
        "avatar_url": "URL",
        "admin": true,
        "signature": "",
        "timezone": "America/Halifax",
        "phone": "",
        "last_sign_in_at": "2021-09-01T15:45:50.456Z",
        "updated_at": "2022-05-04T22:41:15.295Z",
        "created_at": "2019-10-04T10:06:25.581Z",
        "avatar": {
            "medium": "URL",
            "small": "URL",
            "tiny": "URL"
        }
    },
    "team_member": {
        "id": ID,
        "email": "peet@example.com",
        "title": "",
        "first_name": "Peet",
        "last_name": "Peeter",
        "name": "Peet Peeter",
        "avatar_url": "URL",
        "admin": false,
        "signature": null,
        "timezone": null,
        "phone": "",
        "last_sign_in_at": null,
        "updated_at": "2022-05-04T23:05:50.000Z",
        "created_at": "2022-05-04T23:05:50.000Z",
        "avatar": {
            "medium": "URL",
            "small": "URL",
            "tiny": "URL"
        },
        "role": {
            "name": "agent",
            "invited_at": null,
            "joined_at": null
        }
    }
}

Example of unsuccessful response with validation errors:

{
  "email": [
    "is invalid"
  ],
  "phone": [
    "is an invalid number"
  ]
}