HubSpot orange sprocket logo

HOSTED MOCK API REFERENCE

HubSpot Contacts API mock: property mapping and retry handling

Test a properties-based contact importer with separate create and PATCH operations. Check how your client reports duplicate contacts, missing IDs and invalid property values, then compare temporary throttling with an account usage cap.

Explore mock APIs

New registration is paused. Explore the public mock APIs; existing users can still sign in.

Existing user? Configure HubSpot Contacts API · Workspace pricing and limits · Supported operations and behaviours

What to assert in your client

Choose each response explicitly; sending the same email twice does not build a contact database or trigger real duplicate detection. Only single-contact operations are covered. Selected quotas and property policy are approximations, not measurements of a HubSpot account.

Request and selected response examples

Create Contact: API rate limited

Documented Synthetic illustrative example from the catalogue, not a live capture. Run only after installing your own receiver. Replace <your-receiver-token> locally; no request is sent from this page.

HTTP 429 · error · Retry-After: 10

curl / Bash request

printf '%s' '{"properties":{"email":"alex@example.test","firstname":"Alex"}}' | \
curl -i -X POST \
  'https://nottherealapi.com/r/<your-receiver-token>/crm/v3/objects/contacts' \
  -H 'Authorization: Bearer synthetic-hubspot-token' \
  -H 'Content-Type: application/json' \
  --data-binary @-

PowerShell request

$body = '{"properties":{"email":"alex@example.test","firstname":"Alex"}}'
Invoke-WebRequest `
    -UseBasicParsing `
    -Uri 'https://nottherealapi.com/r/<your-receiver-token>/crm/v3/objects/contacts' `
    -Method POST `
    -Headers @{
    Authorization = 'Bearer synthetic-hubspot-token'
    } `
    -ContentType 'application/json' `
    -Body ([Text.Encoding]::UTF8.GetBytes($body))

Selected synthetic response

HTTP 429
content-type: application/json
retry-after: 10

{
  "status": "error",
  "message": "You have reached a rate limit.",
  "correlationId": "example-correlation-id"
}

CRM CRM Contacts API · CRM v3

What can I test with this?

Test contact creation and updates without a live HubSpot account. Exercise property mapping, duplicate contacts, missing records, authentication and write permissions. Switch between short-term rate limits, account usage caps and temporary server errors to check how your connector recovers.

Pinned to CRM v3. Single-contact operations only; batch and multi-status responses are not implemented. Property policy, duplicate detection and quotas are selected approximations.

Useful for

  • Contact ingestion
  • CRM synchronisation
  • Property mapping
  • Scope handling
  • Rate-limit recovery

Supported operations

2 operations

Create Contact

POST /crm/v3/objects/contacts

Creates a CRM contact from a properties object. Use this to check contact field mapping, duplicate rejection and create-response handling.

Request content type: application/json

Request example

{
  "properties": {
    "email": "alex@example.test",
    "firstname": "Alex"
  }
}

Available behaviours (8)

  • Contact created
    Documented

    POST contact properties returns a record with timestamps.

    HTTP 201

    Verify that your client handles a successful response.

  • Missing or invalid access token
    Representative

    Authentication failed; no vendor credential is checked by this mock.

    HTTP 401 · error

    Test credential refresh and authentication recovery.

  • Missing CRM scope
    Representative

    Token is recognized but does not grant contact write access.

    HTTP 403 · error

    Check how your integration reports missing access or permissions.

  • Contact properties rejected
    Representative

    The request is readable but contains a missing or unsupported property.

    HTTP 400 · error

    Test field mapping and useful validation feedback.

  • Duplicate contact
    Representative

    Representative duplicate record rejection; duplicate policy may vary by endpoint and account.

    HTTP 409 · error

    Exercise conflict handling before repeating a write.

  • API rate limited
    Documented

    Short-term API throttle with retry metadata.

    HTTP 429 · error · Retry-After: 10

    Verify bounded backoff and retry handling.

    • Honor Retry-After and reduce request rate.
  • Account API usage cap
    Synthetic

    Synthetic non-transient usage-cap response; consult account usage before retrying.

    HTTP 429 · error

    Check that persistent allocation or billing limits do not cause endless retries.

    • A retry alone may not resolve a usage cap.
  • Temporary service error
    Representative

    Representative HubSpot server failure.

    HTTP 500 · error

    Test recovery and error reporting during simulated service failures.

Update Contact

PATCH /crm/v3/objects/contacts/1001

Updates selected properties on the example contact ID. Reproduce successful updates, missing contacts and shared authentication or rate-limit responses.

Request content type: application/json

Request example

{
  "properties": {
    "jobtitle": "Director"
  }
}

Available behaviours (8)

  • Contact updated
    Documented

    PATCH updates selected contact properties.

    HTTP 200

    Verify that your client handles a successful response.

  • Missing or invalid access token
    Representative

    Authentication failed; no vendor credential is checked by this mock.

    HTTP 401 · error

    Test credential refresh and authentication recovery.

  • Missing CRM scope
    Representative

    Token is recognized but does not grant contact write access.

    HTTP 403 · error

    Check how your integration reports missing access or permissions.

  • Contact properties rejected
    Representative

    The request is readable but contains a missing or unsupported property.

    HTTP 400 · error

    Test field mapping and useful validation feedback.

  • Contact not found
    Representative

    The requested record ID does not exist.

    HTTP 404 · error

    Check how your client handles a missing record or resource.

  • API rate limited
    Documented

    Short-term API throttle with retry metadata.

    HTTP 429 · error · Retry-After: 10

    Verify bounded backoff and retry handling.

    • Honor Retry-After and reduce request rate.
  • Account API usage cap
    Synthetic

    Synthetic non-transient usage-cap response; consult account usage before retrying.

    HTTP 429 · error

    Check that persistent allocation or billing limits do not cause endless retries.

    • A retry alone may not resolve a usage cap.
  • Temporary service error
    Representative

    Representative HubSpot server failure.

    HTTP 500 · error

    Test recovery and error reporting during simulated service failures.

What NotTheRealAPI controls

NotTheRealAPI does not call HubSpot. No real provider account is required. Your integration sends the request to a NotTheRealAPI receiver and receives the selected provider-shaped response.

The receiver stays under NotTheRealAPI at /r/<receiver-token> followed by the operation path. Selecting a behaviour controls the simulated response on that same receiver.

Registration paused

New registration is paused. Sign in to use this module

Scope and safe testing

This independent simulation has no live HubSpot connection or endorsement and does not claim complete API compatibility. No real provider credentials are required. Outcomes remain selected until you change them; these provider fixtures do not persist business records or transition autonomously.

Use synthetic data only. Receiver URLs are secrets. Captured headers and bounded bodies are visible to authorised workspace members without automatic redaction; see privacy and retention.

NotTheRealAPI independently simulates third-party APIs for testing. All provider names and logos are the property of their respective owners. NotTheRealAPI is not affiliated with, sponsored by or endorsed by those providers, and these modules do not connect to their live services. Twilio and all related logos are trademarks of Twilio Inc. or its affiliates.

Browse the full mock API catalogue · Dataverse Accounts API mock: OData success and service protection · Compare workspace limits and pricing · Sign in

HubSpot Contacts API Mock: Test Rate Limits & Errors | NotTheRealAPI