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 |