Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 37 ยท Integrations and API

CRM API: Objects, Search and Pagination

Learn the HubSpot CRM v3 objects API: create, read, update and delete contacts, search with filter groups, paginate with after cursors and batch calls, with a runnable in-memory stand-in.

Every CRM object type (contacts, companies, deals, tickets, and custom objects) shares one API pattern. Learn it once on contacts and you can use it everywhere. The paths follow /crm/v3/objects/{objectType}.

The live API is not callable from this site. Real requests appear as read-only blocks. The runnable code uses a small in-memory stand-in that follows the same shapes (filter groups, cursors) so you can practice the logic. Real limits and fields are documented in HubSpot's developer reference; check it for details.

CRUD in short

Action Request Notes
Create POST /crm/v3/objects/contacts Body {"properties": {...}}
Read one GET /crm/v3/objects/contacts/{id}?properties=email,firstname Only requested properties come back
List GET /crm/v3/objects/contacts?limit=100&after=... Paginated
Update PATCH /crm/v3/objects/contacts/{id} Send only changed properties
Delete DELETE /crm/v3/objects/contacts/{id} Archives the record (recoverable for a time)
Terminal
curl --request POST \
  --url https://api.hubapi.com/crm/v3/objects/contacts \
  --header "Authorization: Bearer $HUBSPOT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"properties":{"email":"[email protected]","firstname":"Ana","lifecyclestage":"lead"}}'

Property names use the internal name (firstname, lifecyclestage), not the label shown in the UI. Enumeration properties need an internal option value (for example lead).

Searching

POST /crm/v3/objects/contacts/search takes a JSON body. Filters inside one filterGroup are joined with AND; multiple filter groups are joined with OR.

JSON
{
  "filterGroups": [
    { "filters": [
      { "propertyName": "lifecyclestage", "operator": "EQ", "value": "lead" },
      { "propertyName": "country", "operator": "EQ", "value": "DE" }
    ] }
  ],
  "properties": ["email", "firstname"],
  "sorts": [{ "propertyName": "createdate", "direction": "DESCENDING" }],
  "limit": 100,
  "after": 0
}

Operators include EQ, NEQ, LT, LTE, GT, GTE, BETWEEN, IN, NOT_IN, HAS_PROPERTY, NOT_HAS_PROPERTY, CONTAINS_TOKEN and NOT_CONTAINS_TOKEN. Search is subject to its own stricter rate limit, and newly changed records may take a few moments to appear in results.

Search body

filters Property, operator, value
AND inside a group All filters must match
OR between groups Any group may match
limit and after Cursor paging

Request only needed properties

1 / 2

An in-memory stand-in

This class mimics create, read, update and search with filter groups, so you can test your query logic without any network.

Python Filter groups: AND inside, OR between (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Pagination

List and search endpoints return at most limit items (the maximum differs by endpoint) plus paging.next.after. Keep sending the after value until it is absent.

Python Loop through pages with an after cursor

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Batch endpoints

For many records, use POST /crm/v3/objects/contacts/batch/create, /batch/update, /batch/read, and /batch/upsert, which take arrays of inputs (up to 100 per request for most of them). They reduce request counts and speed up imports. Batch calls can partly succeed, so read the response for per-item errors.

Python Chunk 250 records into batches of 100

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Practical advice

  • Ask only for the properties you need; returning every property is slow.
  • Use idProperty=email on read/update to address a contact by email instead of ID.
  • Search beats list-and-filter on the client for anything big.
  • Archive deletes are not the same as GDPR permanent deletes; there is a separate endpoint for the latter.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. In a search body, how are two filters in the same filterGroup combined?

    Filters in a group are ANDed; separate groups are ORed.
  2. 2. How do you fetch the next page?

    Cursor-based paging uses the after value from the previous response.
  3. 3. Why use batch endpoints?

    Batching reduces request counts and time, but check each item's result.

Summary

  • All CRM objects share /crm/v3/objects/{type} for create, read, update, delete.
  • Search uses filter groups: AND within, OR between.
  • Paginate with after and batch up to 100 records per call.
  • Use internal property names and request only what you need.

Next: Webhooks, Rate Limits and Reliable Integrations