UniLink API: Contacts Endpoint (Access Your CRM via API)

The /contacts endpoint exposes your UniLink CRM programmatically — sync contacts with external tools, trigger automations, and manage tags without opening the dashboard.

Every email address collected through your UniLink forms, checkout flows, and landing pages lands in your contacts list. The /contacts endpoint gives you programmatic access to that data so you can push it to your email platform, trigger CRM workflows, or run custom segmentation logic in your own tooling. Whether you are syncing new subscribers into Mailchimp, triggering an onboarding sequence in your marketing automation platform, or building a custom reporting tool, the contacts endpoint is the read-write bridge between UniLink and your broader stack.

What the Contacts Endpoint Does

The GET /contacts endpoint returns a paginated list of all contacts in your UniLink CRM. Each contact object contains the core profile fields: id, email, name, tags (array of strings), custom_fields (key-value object), source (which UniLink form or page collected the contact), and subscribed_at (ISO 8601 timestamp). The list endpoint supports filtering by tag, source, and date range, making it possible to extract precise segments without pulling and filtering client-side.

Creating a contact with POST /contacts requires only an email field. All other fields — name, tags, custom fields — are optional at creation and can be added later via PUT. If you attempt to create a contact with an email that already exists in your account, the API returns a 409 Conflict response with the existing contact's ID. This prevents accidental duplicates. To handle "create if not exists, update if exists" logic, first attempt the POST and on 409 use the returned ID to issue a PUT instead.

The custom_fields object accepts any key-value pairs you define — for example, {"company": "Acme", "plan_tier": "pro"}. These fields are stored on the contact record and returned in all GET responses. Custom fields are not pre-defined in the API schema; you can use any string keys. Tags are simpler: they are a flat array of strings like ["subscriber", "course-buyer", "vip"]. When you PUT a contact with a new tags array, the tags are replaced entirely — if you want to add a single tag without removing existing ones, fetch the contact first, append the new tag to the existing array, and send the full updated array.

How to Get Started

1. Generate an API key with write scope from Settings → API in your dashboard at app.unilink.us. Read scope is sufficient for syncing to external tools; write scope is needed for creating or updating contacts.
2. Fetch your first contacts page to understand the data: curl -H "Authorization: Bearer YOUR_KEY" "https://unilink.us/api/v1/contacts?per_page=5". Review the field names, tag formats, and custom field keys that already exist.
3. Test a filtered fetch using a known tag: GET /contacts?tag=subscriber. Confirm the filter returns only contacts with that tag applied.
4. Create a test contact to verify your write access: POST /contacts with body {"email": "test@example.com", "name": "Test User", "tags": ["api-test"]}. Copy the id from the response.
5. Update the test contact with a custom field: PUT /contacts/{id} with body {"custom_fields": {"source_system": "api-test"}}. Confirm the field appears in a subsequent GET response.

How to Use the Contacts Endpoint

1. List all contacts: GET /contacts?page=1&per_page=100 — use pagination to walk through the full list. The response includes total and has_more for loop control.
2. Filter by tag: GET /contacts?tag=vip returns contacts with the "vip" tag. Use this to export segments to email platforms without client-side filtering.
3. Filter by source: GET /contacts?source=homepage-form pulls contacts from a specific form or page. Source values match the names you assign to forms in the dashboard.
4. Filter by date: GET /contacts?start_date=2026-01-01&end_date=2026-01-31 filters by subscribed_at — useful for syncing new contacts since the last run.
5. Add tags to a contact: Fetch the contact with GET /contacts/{id}, append to the tags array, then PUT /contacts/{id} with the full updated array — the PUT replaces tags entirely, so always include existing tags in the array.

Key Settings

Get the Most Out Of the Contacts Endpoint

Design your tag taxonomy before you start creating contacts via API. Tags are the primary segmentation mechanism in UniLink CRM, and they carry through to filtering at the API level. Decide on a consistent naming convention — for example, interest tags, purchase tags, and lifecycle tags — and document it in your integration code. A flat, consistent set of tags is much easier to query and maintain than ad-hoc tags created across multiple systems.

Use the source filter to build per-acquisition-channel dashboards. If you have multiple UniLink forms — a header opt-in, a checkout form, and a lead magnet download — each creates contacts with a different source value. Pulling contacts grouped by source and comparing subscription volume over time gives you the kind of acquisition data that most email platforms do not surface natively without custom event tracking.

Custom fields are the right place to store external system IDs. When you sync a UniLink contact to your CRM, write the external CRM ID back to the contact's custom_fields: {"crm_id": "hs_123456"}. This creates a bidirectional reference so future updates from either system can find the matching record without a fragile email-matching lookup.

The DELETE endpoint for contacts requires admin scope and permanently removes the contact record. For GDPR erasure requests, this is the correct endpoint to use. For contacts who simply unsubscribe from email, update their record with a tag like unsubscribed and respect that tag in your downstream email system — do not delete the contact unless the user has specifically requested erasure, since deleting removes the consent and audit trail as well.

Troubleshooting

• The contacts endpoint base URL is https://unilink.us/api/v1/contacts — authenticate every request with a Bearer token.
• Email is the unique identifier — POSTing a duplicate email returns 409 with the existing contact's ID, which you should then use for a PUT update.
• PUT replaces the entire tags array — always fetch first, merge, then update to preserve existing tags.
• Filter by tag, source, and date range to extract precise segments for external tool syncs.
• Store external system IDs in custom_fields to maintain bidirectional references across your stack.