canonical: https://jentic.com/apis/getmateo.com/getmateo # Getmateo Mateo API Jentic publishes the only available OpenAPI specification for the Mateo API, keeping it validated and agent-ready. Mateo is a GDPR-compliant customer communications platform combining CRM, messaging, and appointment management. The integration v1 REST API exposes 32 endpoints covering appointments, deals, messages, channels, tags, segments, custom fields, deal types, appointment statuses, events, and contact custom field values. Authentication is HTTP Bearer using a per-account integration token. Designed for embedding Mateo inside booking, CRM, and marketing workflows. ## For AI agents Manage Mateo appointments, deals, messages, segments, and contact custom fields through a Bearer-authenticated CRM-style API. ## Scope Does not handle outbound message sending, telephony, or marketing automation triggers - use for CRM, appointment, and contact-data management only. ## Capabilities - Create, list, update, and delete appointments through the /appointment endpoints - Manage sales deals with create, list, update, and delete operations on /deal - List and delete messages, and read message channels through /message and /channel - Maintain custom fields and contact custom field values for flexible CRM data models - Read tags, segments, deal types, appointment statuses, and event records to drive segmentation - Manage appointment custom field values for booking workflows that need extra structured data ## Use cases ### Booking-System Appointment Sync Mirror appointments created in an external booking system into Mateo so that customer-facing messaging stays in sync. The integration calls POST /appointment to create, PATCH /appointment to update, and DELETE /appointment for cancellations. Avoids duplicate-entry overhead for businesses that already run a booking calendar. Example prompt: Call POST /appointment with contactId, datetime, and status, then PATCH the same endpoint when the customer reschedules. ### Sales Pipeline Reporting Pull deal data into a downstream BI tool by listing deals, deal types, and tagging metadata. The integration calls GET /deal, GET /deal_type, and GET /tag. Useful for managers who want a single deal view across Mateo and other CRMs. Example prompt: Call GET /deal and GET /deal_type, join the responses on dealTypeId, and return a pipeline summary by stage. ### Custom Field Hydration Hydrate Mateo contacts with structured data from external systems using contact custom fields. The integration calls POST /contact_custom_field to set values and PATCH or DELETE to maintain them over time. Ideal for integrating account-specific attributes like tier, region, or churn risk. Example prompt: Call POST /contact_custom_field with contactId, customFieldId, and value, then PATCH later to refresh the value when the source data changes. ### AI Agent CRM Concierge An AI agent acts as a Mateo CRM concierge that creates appointments, updates deals, and writes contact custom fields based on conversation context. The agent uses Jentic's intent search to discover the right operation rather than reading docs, and Jentic isolates the Bearer integration token. Time-to-first-update drops from hours to minutes. Example prompt: Search Jentic for 'create a Mateo appointment', load the schema for POST /appointment, and create an appointment for the contact mentioned in the latest agent conversation. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/appointment` | Create an appointment | | PATCH | `/appointment` | Update an appointment | | POST | `/deal` | Create a deal | | PATCH | `/deal` | Update a deal | | POST | `/contact_custom_field` | Set a contact custom field value | | GET | `/segment` | List segments | ## Key resources - **Appointments** — List, create, update, and delete appointments and read appointment statuses - **Deals** — List, create, update, and delete deals and read deal types - **Messages and Channels** — Read message history, delete messages, and list available messaging channels - **Custom Fields** — Maintain custom field definitions and the contact-level values attached to them - **Segments and Tags** — List segments and tags used for customer grouping and routing - **Events** — Read event records associated with contacts for activity feeds ## Why Jentic - **Setup:** Wiring Mateo by hand means setting its bearer auth against the integration host and shaping appointment, deal, and contact payloads for the v1 endpoints yourself. Through Jentic you install once, import the Mateo API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Mateo carries the appointment, deal, and contact targets in the request body rather than a resource id in the path, so you limit the agent to the operations it needs, such as creating an appointment or reading a segment. Because you pick the operation set, edits like updating a deal are not reachable unless you add them. - **Credential handling:** Your Mateo integration token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a Mateo appointment' or 'update a deal', and Jentic returns the matching Mateo operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **HubSpot CRM Contacts API** — Larger CRM platform with broader contact and deal tooling than Mateo - **Pipedrive API** — Sales-pipeline-focused CRM with a similar deal-and-activity model - **Calendly API** — Scheduling tool that pairs with Mateo for inbound booking flows ## FAQ ### Why is there no official OpenAPI spec for the Mateo API? Mateo does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call the Mateo API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Mateo API use? Mateo uses HTTP Bearer authentication with an integration token issued per Mateo workspace. Jentic stores the integration token in its encrypted vault and injects the Authorization header at execution time so the token never enters the agent context. ### Can I create an appointment with the Mateo API? Yes. Call POST /appointment with contactId, datetime, and the relevant appointment status id from GET /appointment_status. The endpoint returns the created appointment's id which you can use for later PATCH or DELETE calls. ### What are the rate limits for the Mateo API? Mateo does not encode rate limits in the spec. Plan for sustained throughput around 5 requests per second per integration token and back off when 429 responses appear; treat the integration endpoints as control-plane traffic rather than high-volume eventing. ### How do I update a Mateo deal through Jentic? Search Jentic for 'update a Mateo deal', load the schema for PATCH /deal, and execute with the dealId and the fields to change. Jentic injects the Bearer token automatically and surfaces the updated record in the response. ### Does the Mateo API support custom fields on contacts? Yes. POST /contact_custom_field sets a value, PATCH updates it, DELETE removes it, and GET /contact_custom_field returns the values currently attached to a contact. Combine with GET /custom_field to discover which custom field definitions exist. ### Can I limit what my agent is allowed to do with the Mateo API? Yes. Jentic One runs self-hosted, so your own rules decide which Mateo operations and credentials the agent can use. Because Mateo carries appointment, deal, and contact targets in the request body rather than a path id, you scope the agent to just the operations it needs, such as POST /appointment to create a booking or GET /segment to read segments. Write operations like PATCH /deal are not reachable unless you explicitly add them to the agent's allowed set.