BIGContacts API Guide

 

BigContacts offers a REST API for securely accessing, adding, updating, and deleting data within your CRM. This guide explains each available endpoint, its purpose, and how to use it.

 

Base URL

 

 

Authentication

 

All API requests must include your access token either in the URL or as a bearer token in the Authorization header.

 

Option 1: In the URL

 

 

Option 2: In the header

 

 

 

Response Format

 

All responses follow this structure:

 

 

1. Users

 

List all users (team members)

 

Endpoint:

 

 

Purpose:
Returns details of all users (team members) in your BigContacts account. Use this when you need to view the user directory or assign records.

 

2. Contacts

 

List all contacts

 

Endpoint:

 

 

Purpose:
Retrieves all contact records visible to the user making the request. Supports pagination.

 

Query Parameters:

• page: Page number (optional)

• results: Results per page (default is 100)

 

 

Filter contacts by creation or update date

 

Endpoint:

 

 

Operators:

• updated, updated_gt, updated_lt, updated_gte, updated_lte

• created, created_gt, created_lt, created_gte, created_lte

 

Example:

 

 

Search contacts by criteria

 

Endpoint:

 

 

Purpose:
Returns contacts matching the given search string in fields like name, company, or associated emails.

 

 

Get one contact by ID

 

Endpoint:

 

 

Purpose:
Returns full contact details for the contact with the given ID.

 

Create a new contact

 

Endpoint:

 

 

Purpose:
Adds a new contact. Send data in JSON format. Required fields:

• first_name

• last_name

• emails.email

 

Example:

 

 

Update a contact

 

Endpoint:

 

 

Purpose:
Updates an existing contact. Fields not included in the request remain unchanged. For array fields (like emails), include all desired values—existing entries will be overwritten.

 

 

Delete a contact

 

Endpoint:

 

 

Purpose:
Deletes a specific contact, if the user has appropriate permissions.

 

 

3. Contact Activity

 

List all activity for a contact

 

Endpoint:

 

 

Purpose:
Returns a list of all activities (calls, meetings, notes, etc.) associated with the contact.

 

 

Get specific activity

 

Endpoint:

 

 

Purpose:
Fetches a single activity record for the contact.

 

 

Add activity to a contact

 

Endpoint:

 

 

Fields:

• title

• activity_type (e.g., "Call", "Meeting")

• description

 

Example:

{ "title": "Follow-up call", "activity_type": "Phone call", "description": "Discussed renewal timeline" }

 

 

Update a contact's activity

 

Endpoint:

 

 

Purpose:
Updates an activity record tied to a specific contact.

 

 

Delete a contact activity

 

Endpoint:

 

 

Purpose:
Deletes an activity record by ID.

 

 

4. Other Data Access

 

Get Meeting List

 

Endpoint:

 

 

Purpose:
Returns all scheduled meetings.

 

 

Get Notes List

 

Endpoint:

 

 

Purpose:
Returns all notes logged into the system.

 

5. Tasks

 

The Tasks API allows you to retrieve, create, update, and delete tasks assigned to users in your BigContacts account. Tasks can be associated with contacts and assigned to one or more users.

 

Get Task List

 

Endpoint:

 

 

Purpose:
Returns all assigned tasks.

 

Get Single Task

 

Endpoint:

 

 

Purpose:
Returns complete details of a specific task identified by its ID.

 

Path Parameter:

• id: Task ID (required)

 

Create Task

 

Endpoint:

 

 

Purpose:
Creates a new task and assigns it to one or more users. At least one associated contact and one date (start or due) are required.

 

Required Fields:

• title: Task title

• start_date or due_date: Task date (YYYY-MM-DD)

• contacts: Contact email, ID, or object

 

Optional Fields:

• description: Task description

• priority: Task priority (u = urgent, h = hot, n = normal; default: n)

• completed: Completion status (default: false)

• is_todo: Whether the task is a to-do item

• assigned_to: User email(s), ID(s), or object(s)

 

Example:

{ "title": "Follow up with client", "description": "Discuss next steps", "priority": "h", "due_date": "2024-01-25", "assigned_to": ["user@example.com"], "contacts": "client@example.com" }

 

Update Task

 

Endpoint:

 

 

Purpose:
Updates an existing task. Only the fields included in the request are modified; all others remain unchanged.

 

Path Parameter:

• id: Task ID (required)

 

Updatable Fields:

• title

• description

• priority

• start_date

• due_date

• completed

• is_todo

• assigned_to

• contacts

 

Delete Task

 

Endpoint:

 

 

Purpose:
Deletes a task permanently if the authenticated user has permission to do so.

 

Path Parameter:

• id: Task ID (required)

 

Notes

• Tasks are scoped to the authenticated user’s customer account.

• The contacts field accepts only one contact (email, ID, or object).

• When multiple users are provided in assigned_to, the system assigns the task to the first valid user found.

• All dates must be in YYYY-MM-DD format.