# Agree.com Contacts API

**Canonical:** https://apis.io/apis/agree-com/agree-com-contacts-api/  
**Provider:** Agree.com — https://apis.io/providers/agree-com/  
**Base URL:** https://secure.agree.com/api/v1  
**Documentation:** https://secure.agree.com/documentation

Agree.com Contacts API is one of 6 APIs that [Agree.com](https://apis.io/providers/agree-com/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification. Tagged areas include Contacts. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, an API reference, a getting-started guide, authentication docs, and an AsyncAPI specification.

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 |

## Operations (6)

| Method | Path | Summary |
|---|---|---|
| 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 |

## Machine-readable artifacts (11)

- **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/agree-com/refs/heads/main/openapi/agree-com-contacts-api-openapi.yml
- **Documentation** — https://secure.agree.com/documentation
- **APIReference** — https://secure.agree.com/documentation
- **GettingStarted** — https://secure.agree.com/documentation#section/Introduction/Quick-Start
- **Authentication** — https://secure.agree.com/documentation#section/Introduction/Authentication
- **ErrorCatalog** — https://raw.githubusercontent.com/api-evangelist/agree-com/refs/heads/main/errors/agree-com-problem-types.yml
- **DataModel** — https://raw.githubusercontent.com/api-evangelist/agree-com/refs/heads/main/data-model/agree-com-data-model.yml
- **Conventions** — https://raw.githubusercontent.com/api-evangelist/agree-com/refs/heads/main/conventions/agree-com-conventions.yml
- **AsyncAPI** — https://raw.githubusercontent.com/api-evangelist/agree-com/refs/heads/main/asyncapi/agree-com-webhooks-asyncapi.yml
- **Webhooks** — https://raw.githubusercontent.com/api-evangelist/agree-com/refs/heads/main/asyncapi/agree-com-webhooks-asyncapi.yml
- **ToolCrosswalk** — https://raw.githubusercontent.com/api-evangelist/agree-com/refs/heads/main/mcp/agree-com-tool-crosswalk.yml

## Other Agree.com APIs (5)

- [Agree.com Agreements API](https://apis.io/apis/agree-com/agree-com-agreements-api/)
- [Agree.com Customers API](https://apis.io/apis/agree-com/agree-com-customers-api/)
- [Agree.com Invoices API](https://apis.io/apis/agree-com/agree-com-invoices-api/)
- [Agree.com Reports API](https://apis.io/apis/agree-com/agree-com-reports-api/)
- [Agree.com Webhooks API](https://apis.io/apis/agree-com/agree-com-webhooks-api/)

## Tags

Contacts

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/agree-com/agree-com-contacts-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/agree-com/.