Integration Row Basics

skill

Read and create records in any REST-API CRM through an Integration row using authenticated GET and POST calls.

Download .md

Integration Row Basics

Read and create records in any REST-API CRM (customer relationship management system) by calling its API through an authenticated Integration row, without ever handling credentials directly.

When to use

  • A task asks you to look up, list, or filter records (contacts, deals, companies) in a CRM.
  • A task asks you to create a new record in a CRM (a contact, a deal, a note, a task).
  • You need to confirm a record exists or check its current field values before acting on it.
  • A workflow step requires pushing data collected elsewhere into a CRM.

Tools

  • http-get: reads records from the CRM REST API (list, search, or fetch a single record by ID).
  • http-post: creates new records in the CRM REST API (contacts, deals, companies, notes, or search endpoints that use POST).

Playbook

  1. Identify the CRM and the exact object type involved (contact, deal, company, note) before making any call.
  2. To read data, call the CRM REST API with http-get (e.g. GET https://api.hubapi.com/crm/v3/objects/contacts). Authentication is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials.
  3. If the read call returns 401/403 or no Integration row exists, stop and message a human via send-message asking them to create the Integration, naming the service and required scopes.
  4. Parse the response and confirm it contains the fields the task needs before proceeding; do not assume shape.
  5. To create a record, call the CRM REST API with http-post (e.g. POST https://api.hubapi.com/crm/v3/objects/contacts) with the minimal required payload for that object type. Authentication is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials.
  6. If the create call returns 401/403 or no Integration row exists, stop and message a human via send-message asking them to create the Integration, naming the service and required scopes.
  7. If a task requires updating or deleting an existing CRM record, this skill cannot do it — PATCH, PUT, and DELETE are not available. Compile the intended change into a file and hand it off to a human via send-message; never imply the update happened.
  8. After a successful http-post create, capture the returned record ID and confirm it in your result so downstream steps can reference the exact record.
  9. Record any CRM-specific quirks you hit (field names, required scopes, pagination limits) so future runs go faster.

Failure modes

  • 401/403 response -> the Integration row is missing or lacks scope; stop and escalate via send-message, naming the service and scopes needed.
  • Empty or unexpected result from http-get -> verify the endpoint path, query params, and object type before retrying.
  • Rate limit (429) response -> back off and retry later; note the limit in memory so future calls pace themselves.
  • CRM API endpoint or schema appears to have changed -> fall back to browser-search to confirm the current API contract before retrying.

Done when

  • A http-get call returns the requested CRM record(s) with the fields the task needed, or confirms none exist.
  • A http-post call successfully creates the CRM record and returns a new record ID.
  • Any blocked update/delete request is documented in a handoff file and a human has been notified via send-message.