Skip to main content

​
Overview

The Contacts API allows you to manage customers, suppliers, optometrists, and other contacts in your system. Contacts are used in invoices, quotations, purchases, and prescriptions.

​
Contact Object

​
id
integer
Unique identifier for the contact
​
name
string
Contact name or company name
​
email
string
Primary email address
​
phone
string
Primary phone number
​
phone_primary
string
Primary phone
​
phone_secondary
string
Secondary phone
​
mobile
string
Mobile phone
​
fax
string
Fax number
​
contact_type
enum
Contact type: customer, supplier, optometrist, both
​
identification_type
enum
ID type: rnc, cedula, passport, other
​
identification_number
string
ID or tax number
​
status
enum
Contact status: active, inactive
​
credit_limit
decimal
Credit limit for customer contacts
​
observations
string
Additional notes or observations
​
birth_date
date
Date of birth (for individual contacts)
​
gender
enum
Gender: male, female, other
​
addresses
array
Array of contact addresses
​
relationships
array
Related contacts (family members, etc.)

​
List Contacts

Retrieve a paginated list of contacts.

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination
​
per_page
integer
default:"15"
Number of items per page
​
filter[contact_type]
string
Filter by type: customer, supplier, optometrist
​
filter[status]
string
Filter by status: active, inactive
​
search
string
Search by name, email, phone, or ID number
​
sort
string
default:"name"
Sort field: name, email, -created_at

​
Response

{
  "data": [
    {
      "id": 45,
      "name": "Acme Corporation",
      "email": "[email protected]",
      "phone": "+1-809-555-0123",
      "contact_type": "customer",
      "identification_type": "rnc",
      "identification_number": "130123456",
      "status": "active",
      "credit_limit": "50000.00",
      "primary_address": {
        "street": "123 Main St",
        "city": "Santo Domingo",
        "country": "Dominican Republic"
      },
      "created_at": "2024-01-10T08:00:00Z",
      "updated_at": "2024-03-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 12,
    "per_page": 15,
    "total": 173
  }
}

​
Example

curl -X GET "https://acme.yourdomain.com/api/v1/contacts?filter[contact_type]=customer&search=acme" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

​
Get Contact

Retrieve a specific contact by ID, including related invoices, quotations, and prescriptions.

​
Path Parameters

​
id
integer
required
Contact ID

​
Response

{
  "data": {
    "id": 45,
    "name": "Acme Corporation",
    "email": "[email protected]",
    "phone_primary": "+1-809-555-0123",
    "mobile": "+1-809-555-0124",
    "contact_type": "customer",
    "identification_type": "rnc",
    "identification_number": "130123456",
    "status": "active",
    "credit_limit": "50000.00",
    "primary_address": {
      "id": 78,
      "street": "123 Main St",
      "city": "Santo Domingo",
      "state": "Distrito Nacional",
      "postal_code": "10100",
      "country": "Dominican Republic",
      "is_primary": true
    },
    "addresses": [
      {
        "id": 78,
        "street": "123 Main St",
        "city": "Santo Domingo",
        "is_primary": true
      }
    ],
    "relationships": [
      {
        "id": 46,
        "name": "Jane Doe",
        "description": "Spouse"
      }
    ],
    "stats": {
      "total_invoices": 42,
      "total_quotations": 15,
      "total_invoiced": "125000.00",
      "total_paid": "100000.00",
      "pending_amount": "25000.00"
    },
    "invoices": [
      // Latest 10 invoices
    ],
    "quotations": [
      // Latest 10 quotations
    ]
  }
}

​
Create Contact

Create a new contact.

​
Request Body

​
name
string
required
Contact name or company name
​
email
string
Email address
​
phone_primary
string
Primary phone number
​
phone_secondary
string
Secondary phone number
​
mobile
string
Mobile phone number
​
contact_type
enum
required
Contact type: customer, supplier, optometrist, both
​
identification_type
enum
ID type: rnc, cedula, passport, other
​
identification_number
string
ID or tax number
​
status
enum
default:"active"
Status: active, inactive
​
credit_limit
decimal
default:"0"
Credit limit (for customers)
​
observations
string
Additional notes
​
birth_date
date
Date of birth (YYYY-MM-DD)
​
gender
enum
Gender: male, female, other
​
primary_address
object
Primary address information
​
primary_address.street
string
Street address
​
primary_address.city
string
City
​
primary_address.state
string
State or province
​
primary_address.postal_code
string
Postal code
​
primary_address.country
string
Country

​
Response

{
  "data": {
    "id": 180,
    "name": "New Customer Corp",
    "email": "[email protected]",
    "contact_type": "customer",
    "status": "active",
    "created_at": "2024-03-20T14:00:00Z"
  },
  "message": "Contact created successfully."
}

​
Example

curl -X POST https://acme.yourdomain.com/api/v1/contacts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Customer Corp",
    "email": "[email protected]",
    "phone_primary": "+1-809-555-9999",
    "contact_type": "customer",
    "identification_type": "rnc",
    "identification_number": "130999888",
    "credit_limit": 25000,
    "primary_address": {
      "street": "456 Business Ave",
      "city": "Santiago",
      "country": "Dominican Republic"
    }
  }'

​
Update Contact

Update an existing contact.

​
Path Parameters

​
id
integer
required
Contact ID

​
Request Body

Same as Create Contact. All fields are optional.

​
Response

{
  "data": {
    "id": 180,
    "credit_limit": "35000.00",
    "updated_at": "2024-03-20T15:30:00Z"
  },
  "message": "El contacto ha sido actualizado exitosamente."
}

​
Delete Contact

Delete a contact.
Contacts with associated invoices, quotations, or payments cannot be deleted. Set their status to inactive instead.

​
Path Parameters

​
id
integer
required
Contact ID

​
Response

{
  "message": "El contacto ha sido eliminado exitosamente."
}

​
Check Duplicates

Check if a contact with the same email or identification number already exists.

​
Query Parameters

​
email
string
Email to check
​
identification_number
string
ID number to check

​
Response

{
  "duplicates": [
    {
      "id": 45,
      "name": "Acme Corporation",
      "email": "[email protected]",
      "match_type": "email"
    }
  ]
}

​
Manage Relationships

Contacts can be related to other contacts (useful for family members, business partners, etc.).

​
Add Relationship

Link a related contact.

​
Request Body

​
related_contact_id
integer
required
ID of the contact to relate
​
description
string
Relationship description (e.g., “Spouse”, “Parent”, “Business Partner”)

​
Remove Relationship

Remove a contact relationship.

​
Contact Import

Bulk import contacts from CSV files.

​
Create Import

Upload a CSV file for import.

​
Process Import

Process the uploaded file and create contacts.

​
Search Contacts

The search functionality works across multiple fields: 
curl -X GET "https://acme.yourdomain.com/api/v1/contacts?search=john" \
  -H "Authorization: Bearer YOUR_TOKEN"
Searches:
  • Name
  • Email
  • Phone numbers
  • Identification number

Invoices

Create invoices for contacts

Quotations

Send quotations to contacts

Payments

Track customer payments

Build docs developers (and LLMs) love

Get started for freeTalk to us