CRM API Endpoint Documentation

Welcome to the CRM API Endpoint documentation! This guide provides an in-depth look at the API endpoints for managing contacts within the CRM system. As a developer integrating with this CRM, you'll find detailed information on how to create, update, delete, and search for contacts using various parameters. By following the examples and code snippets provided, you'll be able to seamlessly integrate your application with our CRM and enhance the user experience.

POST - Create a New Contact

The POST method allows you to create a new contact within the CRM system. In this section, we will explore the necessary parameters and provide examples for successfully adding a contact using the POST method.

Endpoint

POST https://api.botw.org/crm/{listing_id}

Headers

  • Authorization: Bearer {Your_API_Key} 
  • Content-Type: application/x-www-form-urlencoded

Path Parameters

  • listing_id: The listing ID associated with the campaign. (Required)

Request Parameters

  • first_name: The contact's first name. (Optional)
  • last_name: The contact's last name. (Optional)
  • email: The contact's email address. (Required if phone is not provided)
  • phone: The contact's phone number. (Required if email is not provided)

Example Request

POST https://api.botw.org/crm/123
Authorization: Bearer Your_API_Key
Content-Type: application/x-www-form-urlencoded

first_name=John&last_name=Doe&email=johndoe@example.com&phone=15551234567

Response

  • status: The status of the request (success or error).
  • message: A message describing the result of the request.

Example Response

{
  "status": "success",
  "message": "New contact successfully updated."
}

HTTP Status Codes

  • 201 Created: The contact has been successfully created.
  • 400 Bad Request: Invalid input parameters or missing required fields.
  • 403 Forbidden: Invalid API key or unauthorized access.
  • 500 Internal Server Error: An error occurred on the server while processing the request.

Please note that the contact will not be created if the provided email or phone number has been blacklisted.

PUT - Update (or Create if not exists) a Contact

The PUT method enables you to update an existing contact in the CRM system. This section will provide insights into the required parameters and give examples of how to effectively update a contact using the PUT method.

Endpoint

PUT https://api.botw.org/crm/{listing_id}

Headers

  • Authorization: Bearer {Your_API_Key} 
  • Content-Type: application/x-www-form-urlencoded

Path Parameters

  • listing_id: The listing ID associated with the campaign. (Required)

Request Parameters

  • id: The contact ID. If this value is provided and found, the contact will be updated. If no contact is found with the given ID, a new contact will be created. (Optional)
  • first_name: The contact's first name. (Optional)
  • last_name: The contact's last name. (Optional)
  • email: The contact's email address. (Required if phone is not provided and no contact ID is given)
  • phone: The contact's phone number. (Required if email is not provided and no contact ID is given)

Example Request

PUT https://api.botw.org/crm/123
Authorization: Bearer Your_API_Key
Content-Type: application/x-www-form-urlencoded

id=1&first_name=John&last_name=Doe&email=johndoe@example.com&phone=15551234567

Response

  • status: The status of the request (success or error).
  • message: A message describing the result of the request.

Example Response

{
  "status": "success",
  "message": "Contact successfully updated."
}

HTTP Status Codes

  • 200 OK: The contact has been successfully updated.
  • 201 Created: The contact has been successfully created.
  • 400 Bad Request: Invalid input parameters or missing required fields.
  • 403 Forbidden: Invalid API key or unauthorized access.
  • 404 Not Found: The contact ID provided was not found.
  • 500 Internal Server Error: An error occurred on the server while processing the request.

Please note that the contact will not be updated or created if the provided email or phone number has been blacklisted.

DELETE - Delete an Existing Contact

The DELETE method allows you to remove a contact from the CRM system. In this section, you'll learn about the necessary parameters and see examples demonstrating how to delete a contact using the DELETE method.

Endpoint

DELETE https://api.botw.org/crm/{listing_id}

Headers

  • Authorization: Bearer {Your_API_Key} 
  • Content-Type: application/x-www-form-urlencoded

Path Parameters

  • listing_id: The listing ID associated with the campaign. (Required)

Request Parameters

  • id: The contact ID to be deleted. (Required if both email and phone are not provided)
  • email: The contact's email address to be deleted. (Required if both contact ID and phone are not provided)
  • phone: The contact's phone number to be deleted. (Required if both contact ID and email are not provided)

Note: At least one of the parameters (id, email, or phone) must be provided.

Example Request

DELETE https://api.botw.org/crm/123
Authorization: Bearer Your_API_Key
Content-Type: application/x-www-form-urlencoded

id=1

Response

  • status: The status of the request (success or error).
  • message: A message describing the result of the request.

Example Response

{
  "status": "success",
  "message": "Contact deleted successfully."
}

HTTP Status Codes

  • 202 Accepted: The contact has been successfully deleted.
  • 400 Bad Request: Invalid input parameters or missing required fields.
  • 403 Forbidden: Invalid API key or unauthorized access.
  • 404 Not Found: The contact could not be found based on the provided parameters.
  • 500 Internal Server Error: An error occurred on the server while processing the request.

GET - Fetch Contacts Associated with Campaign or Search and Filter Contacts

The GET method enables you to retrieve contact information from the CRM system. This section will guide you through the parameters and provide examples on how to effectively search and retrieve contact data using the GET method.

Endpoint

GET https://api.botw.org/crm/{listing_id}

Headers

  • Authorization: Bearer {Your_API_Key}

Path Parameters

  • listing_id: The listing ID associated with the campaign. (Required)

Query Parameters

  • id: The contact ID to search for. (Optional)
  • first_name: The contact's first name to search for. (Optional)
  • last_name: The contact's last name to search for. (Optional)
  • name: The contact's full name (first name or last name) to search for. (Optional)
  • email: The contact's email address to search for. (Optional)
  • phone: The contact's phone number to search for. (Optional)

Note: At least one of the query parameters must be provided to filter the results.

Example Request

GET https://api.botw.org/crm/123?email=johndoe@example.com
Authorization: Bearer Your_API_Key

Response

  • status: The status of the request (success or error).
  • message: A message describing the result of the request.
  • data: An array of objects containing the contact information.

Example Response

{
  "status": "success",
  "message": "1 record(s) found.",
  "data": {
    "results": [
      {
        "contact_id": 1,
        "contact_unique_id": "l-12345",
        "contact_first_name": "John",
        "contact_last_name": "Doe",
        "contact_email": "johndoe@example.com",
        "contact_phone": "15551234567",
        "contact_created_date": "2021-01-01 00:00:00",
        "contact_ip_address": "192.168.1.1",
        "contact_source": "api",
        "contact_status": "active"
      }
    ]
  }
}

HTTP Status Codes

  • 200 OK: The request has been successfully completed.
  • 400 Bad Request: Invalid input parameters or missing required fields.
  • 403 Forbidden: Invalid API key or unauthorized access.
  • 404 Not Found: No contacts found based on the provided parameters.
  • 500 Internal Server Error: An error occurred on the server while processing the request.

Troubleshooting and Support

We hope this documentation has provided you with a clear understanding of the CRM API endpoints and their usage. If you encounter any issues or have questions while working with the CRM API, please don't hesitate to contact our support team at https://help.botw.org/ or via email at service@botw.org. We are always here to assist you and ensure a smooth integration experience.