Agree.com Contacts API

Manage your organization's contacts - the people and companies you do business with. ## Overview Contacts are the foundation of your billing workflow. Before you can send an invoice, you need someone to send it to. Contacts store customer information like name, email, company, and job title. **Key concepts:** - Each contact belongs to a single organization - Email addresses must be unique within your organization - Contacts can be created explicitly via the API, or automatically when you send an invoice to a new email address - Deleting a contact is a soft delete - the record is retained for historical invoices ## Creating a Contact To add a new contact to your address book: ```bash curl -X POST https://api.agree.com/api/v1/contacts \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contact": { "name": "Jane Smith", "email": "jane@acme.com", "company": "Acme Corporation", "title": "CFO" } }' ``` **Response:** ```json { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Jane Smith", "email": "jane@acme.com", "company": "Acme Corporation", "title": "CFO", "address": null, "organization_id": "660e8400-e29b-41d4-a716-446655440000", "inserted_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:30:00Z" } } ``` ## Using Contacts with Invoices Once you have a contact, you can reference them when creating invoices. There are two ways to associate a contact with an invoice: ### Option 1: Use `contact_id` If you already have a contact, pass their ID: ```json { "invoice": { "contact_id": "550e8400-e29b-41d4-a716-446655440000", "amount": {"amount": 10000, "currency": "USD"} } } ``` ### Option 2: Use `billing_contact` Pass contact details directly - this will find or create the contact automatically: ```json { "invoice": { "billing_contact": { "email": "jane@acme.com", "name": "Jane Smith", "company": "Acme Corporation" }, "amount": {"amount": 10000, "currency": "USD"} } } ``` If a contact with that email already exists, their details will be updated. If not, a new contact is created. ## Listing and Filtering Contacts Retrieve contacts with optional filtering: ```bash # Get all contacts curl https://api.agree.com/api/v1/contacts \ -H "Authorization: Bearer YOUR_API_KEY" # Search by email curl "https://api.agree.com/api/v1/contacts?email=jane" \ -H "Authorization: Bearer YOUR_API_KEY" # Filter by company curl "https://api.agree.com/api/v1/contacts?company=acme" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Query Parameters | Parameter | Type | Description | |-----------|------|-------------| | `page` | integer | Page number (default: 1) | | `page_size` | integer | Items per page (default: 10, max: 100) | | `email` | string | Filter by email address (fuzzy search) | | `company` | string | Filter by company name (fuzzy search) | ## Updating a Contact Update contact details using PUT: ```bash curl -X PUT https://api.agree.com/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contact": { "title": "CEO", "company": "Acme Corp International" } }' ``` ## Deleting a Contact Delete a contact by ID: ```bash curl -X DELETE https://api.agree.com/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Note:** This performs a soft delete. The contact record is retained for historical purposes (existing invoices will still show the contact information), but will no longer appear in your contacts list. ## Fields Reference | Field | Type | Description | |-------|------|-------------| | `id` | UUID | Unique contact identifier | | `name` | string | Contact's full name (required) | | `email` | string | Contact's email address (required, unique per organization) | | `company` | string | Company or organization name | | `title` | string | Job title or role | | `address` | string | Mailing address | | `organization_id` | UUID | Your organization's ID | | `inserted_at` | datetime | When the contact was created | | `updated_at` | datetime | When the contact was last updated |

GitHub OpenAPI

Operations 6

GET /api/v1/contacts List contacts #
POST /api/v1/contacts Create contact #
DELETE /api/v1/contacts/{id} Delete contact #
GET /api/v1/contacts/{id} Get contact #
PATCH /api/v1/contacts/{id} Update contact #
PUT /api/v1/contacts/{id} Update contact #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/agree-com:agree-com-contacts-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

agree-com-contacts-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  description: '# Introduction


    Welcome to the Agree API! Agree is a payments and agreements platform that helps businesses send invoices, collect payments, and manage customer relationships. This API lets you integrate Agree''s capabilities directly into your application. ## What You Can Do


    With the Agree API, you can:


    - **Create and send invoices** to customers with flexible payment options (ACH, credit card, wire transfer)

    - **Manage contacts** in your organization''s address book

    - **Set up recurring invoices** with customizable schedules

    - **Receive real-time notifications** via webhooks when payments are made or invoices change status

    - **Track payment status** and history programmatically


    ## Quick Start


    Here''s how to send your first invoice in three API calls:


    ### 1. Get Your API Key


    Generate an API key in your Agree dashboard under **Settings > API Keys**. Keep this key secure - it provides full access to your organization''s data. ### 2. Create a Contact


    First, add the customer you want to invoice:


    ```bash

    curl -X POST https://api.agree.com/api/v1/contacts \

    -H "Authorization: Bearer YOUR_API_KEY" \

    -H "Content-Type: application/json" \

    -d ''{

    "contact": {

    "name": "Jane Smith",

    "email": "jane@example.com",

    "company": "Acme Corp"

    }

    }''

    ```


    ### 3. Create and Send an Invoice


    Now create and send an invoice for that contact. You can use the convenience endpoint to do both in one request:


    ```bash

    curl -X POST https://api.agree.com/api/v1/invoices/create_and_send \

    -H "Authorization: Bearer YOUR_API_KEY" \

    -H "Content-Type: application/json" \

    -d ''{

    "invoice": {

    "billing_contact": {

    "email": "jane@example.com"

    },

    "amount": {"amount": 10000, "currency": "USD"},

    "payment_methods": ["card", "ach"],

    "due_at": "2025-02-01T00:00:00Z",

    "memo": "Consulting services - January 2025"

    }

    }''

    ```


    The invoice will be created and immediately sent to the customer via email. They''ll receive a payment link where they can pay using their preferred method. **Alternative:** You can also create the invoice first with `POST /api/v1/invoices`, then send it later with `POST /api/v1/invoices/:id/send` if you need to review or modify it before sending. ### 4. Get Notified When They Pay


    Set up a webhook to know when the invoice is paid:


    ```bash

    curl -X POST https://api.agree.com/api/v1/webhook_endpoints \

    -H "Authorization: Bearer YOUR_API_KEY" \

    -H "Content-Type: application/json" \

    -d ''{

    "webhook_endpoint": {

    "url": "https://your-app.com/webhooks/agree",

    "events": ["invoice.paid", "invoice.failed"]

    }

    }''

    ```


    Save the `secret` from the response - you''ll need it to verify webhook signatures. ## How Resources Connect


    Understanding how Agree''s resources relate to each other will help you build effective integrations:


    ```

    Contacts ──────► Invoices ──────► Webhooks

    │ │ │

    │ │ │

    ▼ ▼ ▼

    People you Payment Real-time

    do business requests notifications

    with you send when things

    to contacts happen

    ```


    - **Contacts** are people or companies in your address book. You can create contacts explicitly, or they''re created automatically when you send an invoice to a new email address. - **Invoices** are payment requests sent to contacts. Each invoice has an amount, due date, and accepted payment methods. Invoices progress through a lifecycle from created → sent → paid (or failed/canceled). - **Webhooks** notify your application when invoice events occur. This lets you update your systems in real-time without polling. ## Base URL


    All API requests should be made to:


    ```

    https://api.agree.com/api/v1

    ```


    ## Authentication


    All endpoints require Bearer token authentication. Include your API key in the Authorization header:


    ```

    Authorization: Bearer YOUR_API_KEY

    ```


    Keep your API key secure. If compromised, regenerate it immediately in your dashboard. ## Request Format


    Send request bodies as JSON with the `Content-Type: application/json` header. ## Response Format


    All successful responses return JSON with a `data` wrapper:


    ```json

    {

    "data": { ...'
  title: Agree Contacts API
  version: 1.0.0
servers:
- url: https://secure.agree.com
  variables: {}
security: []
tags:
- description: 'Manage your organization''s contacts - the people and companies you do business with. ## Overview


    Contacts are the foundation of your billing workflow. Before you can send an invoice, you need someone to send it to. Contacts store customer information like name, email, company, and job title. **Key concepts:**


    - Each contact belongs to a single organization

    - Email addresses must be unique within your organization

    - Contacts can be created explicitly via the API, or automatically when you send an invoice to a new email address

    - Deleting a contact is a soft delete - the record is retained for historical invoices


    ## Creating a Contact


    To add a new contact to your address book:


    ```bash

    curl -X POST https://api.agree.com/api/v1/contacts \

    -H "Authorization: Bearer YOUR_API_KEY" \

    -H "Content-Type: application/json" \

    -d ''{

    "contact": {

    "name": "Jane Smith",

    "email": "jane@acme.com",

    "company": "Acme Corporation",

    "title": "CFO"

    }

    }''

    ```


    **Response:**


    ```json

    {

    "data": {

    "id": "550e8400-e29b-41d4-a716-446655440000",

    "name": "Jane Smith",

    "email": "jane@acme.com",

    "company": "Acme Corporation",

    "title": "CFO",

    "address": null,

    "organization_id": "660e8400-e29b-41d4-a716-446655440000",

    "inserted_at": "2025-01-15T10:30:00Z",

    "updated_at": "2025-01-15T10:30:00Z"

    }

    }

    ```


    ## Using Contacts with Invoices


    Once you have a contact, you can reference them when creating invoices. There are two ways to associate a contact with an invoice:


    ### Option 1: Use `contact_id`


    If you already have a contact, pass their ID:


    ```json

    {

    "invoice": {

    "contact_id": "550e8400-e29b-41d4-a716-446655440000",

    "amount": {"amount": 10000, "currency": "USD"}

    }

    }

    ```


    ### Option 2: Use `billing_contact`


    Pass contact details directly - this will find or create the contact automatically:


    ```json

    {

    "invoice": {

    "billing_contact": {

    "email": "jane@acme.com",

    "name": "Jane Smith",

    "company": "Acme Corporation"

    },

    "amount": {"amount": 10000, "currency": "USD"}

    }

    }

    ```


    If a contact with that email already exists, their details will be updated. If not, a new contact is created. ## Listing and Filtering Contacts


    Retrieve contacts with optional filtering:


    ```bash

    # Get all contacts

    curl https://api.agree.com/api/v1/contacts \

    -H "Authorization: Bearer YOUR_API_KEY"


    # Search by email

    curl "https://api.agree.com/api/v1/contacts?email=jane" \

    -H "Authorization: Bearer YOUR_API_KEY"


    # Filter by company

    curl "https://api.agree.com/api/v1/contacts?company=acme" \

    -H "Authorization: Bearer YOUR_API_KEY"

    ```


    ### Query Parameters


    | Parameter | Type | Description |

    |-----------|------|-------------|

    | `page` | integer | Page number (default: 1) |

    | `page_size` | integer | Items per page (default: 10, max: 100) |

    | `email` | string | Filter by email address (fuzzy search) |

    | `company` | string | Filter by company name (fuzzy search) |


    ## Updating a Contact


    Update contact details using PUT:


    ```bash

    curl -X PUT https://api.agree.com/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000 \

    -H "Authorization: Bearer YOUR_API_KEY" \

    -H "Content-Type: application/json" \

    -d ''{

    "contact": {

    "title": "CEO",

    "company": "Acme Corp International"

    }

    }''

    ```


    ## Deleting a Contact


    Delete a contact by ID:


    ```bash

    curl -X DELETE https://api.agree.com/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000 \

    -H "Authorization: Bearer YOUR_API_KEY"

    ```


    **Note:** This performs a soft delete. The contact record is retained for historical purposes (existing invoices will still show the contact information), but will no longer appear in your contacts list.'
  name: Contacts
paths:
  /api/v1/contacts:
    get:
      callbacks: {}
      description: Returns a paginated list of contacts for the authenticated organization.
      operationId: AgreeWeb.API.V1.ContactController.index
      parameters:
      - description: 'Page number (default: 1)'
        in: query
        name: page
        required: false
        schema:
          type: integer
      - description: 'Items per page (default: 10)'
        in: query
        name: page_size
        required: false
        schema:
          type: integer
      - description: Filter by email (fuzzy search)
        in: query
        name: email
        required: false
        schema:
          type: string
      - description: Filter by company name (fuzzy search)
        in: query
        name: company
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactsResponse'
          description: Contacts list
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
          description: Unauthorized
      security:
      - bearer: []
      summary: List contacts
      tags:
      - Contacts
    post:
      callbacks: {}
      description: 'Creates a new contact for the authenticated organization.


        If a user with the provided email doesn''t exist, one will be created automatically.

        The email must be unique within the organization''s contacts.'
      operationId: AgreeWeb.API.V1.ContactController.create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactParams'
        description: Contact params
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
          description: Contact created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
          description: Unauthorized
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Validation errors
      security:
      - bearer: []
      summary: Create contact
      tags:
      - Contacts
  /api/v1/contacts/{id}:
    delete:
      callbacks: {}
      description: Deletes a contact by ID.
      operationId: AgreeWeb.API.V1.ContactController.delete
      parameters:
      - description: Contact ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Contact deleted
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not found
      security:
      - bearer: []
      summary: Delete contact
      tags:
      - Contacts
    get:
      callbacks: {}
      description: Returns a single contact by ID.
      operationId: AgreeWeb.API.V1.ContactController.show
      parameters:
      - description: Contact ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
          description: Contact
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not found
      security:
      - bearer: []
      summary: Get contact
      tags:
      - Contacts
    patch:
      callbacks: {}
      description: Updates an existing contact.
      operationId: AgreeWeb.API.V1.ContactController.update(2)
      parameters:
      - description: Contact ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactParams'
        description: Contact params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
          description: Contact updated
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Validation errors
      security:
      - bearer: []
      summary: Update contact
      tags:
      - Contacts
      x-operation-id-source: normalized
      x-operation-id-original: AgreeWeb.API.V1.ContactController.update (2)
    put:
      callbacks: {}
      description: Updates an existing contact.
      operationId: AgreeWeb.API.V1.ContactController.update
      parameters:
      - description: Contact ID (UUID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactParams'
        description: Contact params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactResponse'
          description: Contact updated
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Validation errors
      security:
      - bearer: []
      summary: Update contact
      tags:
      - Contacts
components:
  schemas:
    ContactParams:
      description: Parameters for creating or updating a contact
      example:
        contact:
          company: Acme Inc
          email: john.doe@example.com
          name: John Doe
          title: CEO
      properties:
        contact:
          properties:
            address:
              description: Contact's mailing address
              type:
              - string
              - 'null'
            company:
              description: Contact's company name
              type:
              - string
              - 'null'
            email:
              description: Contact's email address
              format: email
              type: string
            name:
              description: Contact's full name
              type: string
            title:
              description: Contact's job title
              type:
              - string
              - 'null'
          required:
          - name
          - email
          type: object
      required:
      - contact
      title: ContactParams
      type: object
    Unauthorized:
      description: Authentication required or invalid credentials
      example:
        error: Invalid or missing API key
      properties:
        error:
          description: Error message
          type: string
      title: Unauthorized
      type: object
    ContactsResponse:
      description: Response containing a list of contacts
      properties:
        data:
          description: List of contacts
          items:
            $ref: '#/components/schemas/Contact'
          type: array
        pagination:
          description: Pagination information
          properties:
            page:
              description: Current page number
              type: integer
            page_size:
              description: Number of items per page
              type: integer
            total_entries:
              description: Total number of contacts
              type: integer
            total_pages:
              description: Total number of pages
              type: integer
          required:
          - page
          - page_size
          - total_pages
          - total_entries
          type: object
      required:
      - data
      - pagination
      title: ContactsResponse
      type: object
    BadRequest:
      description: Invalid request parameters
      example:
        error: Invalid page or page_size
      properties:
        error:
          description: Error message
          type: string
      title: BadRequest
      type: object
    Error:
      description: Error response with field-specific error messages
      example:
        errors:
          amount:
          - can't be blank
          recurring_options:
          - is invalid
      properties:
        errors:
          additionalProperties:
            items:
              type: string
            type: array
          description: Map of field names to arrays of error messages
          type: object
      title: Error
      type: object
    Forbidden:
      description: Access denied to the requested resource
      example:
        error: You do not have access to this resource
      properties:
        error:
          description: Error message
          type: string
      title: Forbidden
      type: object
    Contact:
      description: A contact in the organization's address book
      example:
        address: 123 Main St, New York, NY 10001
        company: Acme Inc
        email: john.doe@example.com
        id: 550e8400-e29b-41d4-a716-446655440000
        inserted_at: '2024-01-15T10:30:00Z'
        name: John Doe
        organization_id: 660e8400-e29b-41d4-a716-446655440000
        title: CEO
        updated_at: '2024-01-15T10:30:00Z'
      properties:
        address:
          description: Contact's mailing address
          type:
          - string
          - 'null'
        company:
          description: Contact's company name
          type:
          - string
          - 'null'
        email:
          description: Contact's email address
          format: email
          type: string
        id:
          description: Unique contact identifier
          format: uuid
          type: string
        inserted_at:
          description: When the contact was created
          format: date-time
          type: string
        name:
          description: Contact's full name
          type: string
        organization_id:
          description: Organization that owns this contact
          format: uuid
          type: string
        title:
          description: Contact's job title
          type:
          - string
          - 'null'
        updated_at:
          description: When the contact was last updated
          format: date-time
          type: string
      required:
      - id
      - name
      - email
      - organization_id
      title: Contact
      type: object
    ContactResponse:
      description: Response containing a single contact
      properties:
        data:
          $ref: '#/components/schemas/Contact'
      required:
      - data
      title: ContactResponse
      type: object
    NotFound:
      description: Resource not found error
      example:
        error: Not found
      properties:
        error:
          description: Error message
          type: string
      title: NotFound
      type: object
  securitySchemes:
    bearer:
      description: API key authentication via Bearer token
      scheme: bearer
      type: http
x-provenance:
  method: harvested
  publisher: Agree.com
  source: https://secure.agree.com/documentation/openapi
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)