# 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.