We’re excited to partner with you and help our mutual customers get the maximum value from using both our platforms together.
This document outlines the minimum API capabilities we need from a CRM partner in order to build and maintain a standard integration with TalentLynk. Our use case is intentionally simple and focuses on four main areas:
Basic contact information
Contact search
Activity tracking
Contextual information / metadata
Where possible, we prefer RESTful, JSON-based APIs with secure server-to-server authentication (OAuth2 or API key / client credentials).
1. Basic Contact Information
We need to be able to read and update basic contact details for key CRM entities (for example: candidates, clients, companies, or equivalent entities in your system).
Required capabilities
READ / GET
Ability to retrieve a single record for:
Candidate (or equivalent)
Client contact (or equivalent)
Company / Account (or equivalent)
The response for each entity should include at minimum:
Unique ID
Name (first name, last name and/or full name)
Email address(es)
Phone number(s)
UPDATE / PUT/PATCH
Ability to update an existing record’s phone number(s) and email address(es) for:
Candidate
Client contact
Company / Account
How TalentLynk uses this
Contact creation in TalentLynk:
We use the name, email and phone number from the CRM to create or match a contact record in TalentLynk, so calls and messages are correctly associated with that person/company.Phone number validation & cleanup:
TalentLynk validates phone numbers (for example, to ensure E.164 format).If a number is invalid, we show an error in our UI and allow the user to correct it (often just picking the right country code).
Once corrected, we optionally push the clean number back into the CRM via your update endpoint.
This creates an easy workflow for users to keep CRM data clean, correct and up to date.
2. Contact Search
This is one of the most important requirements for a smooth integration.
We need to be able to search CRM entities by phone number and email so that we can automatically match incoming and outgoing communications in TalentLynk to the correct records in the CRM.
Required capabilities
Search candidate/contact entities by phone number
Search candidate/contact entities by email address
Ideally, search companies / accounts by phone and email as well (if applicable)
The search endpoints should:
Accept a phone number or email as a query parameter or request body field
Be able to fuzzy match on phone number. We generally send only the nationally relevant number to account for different formats.
Alternatively, if your CRM does strict number validation, support matching by E.164 format.
Return zero, one, or multiple matching records
Include the same key fields as above (ID, name, email, phone)
How TalentLynk uses this
When a call or message occurs in TalentLynk with a number that's not already present in our DB, we send the phone number or email to your search endpoint.
If exactly one matching record is returned, we automatically link the TalentLynk contact to that CRM record.
If there are multiple matches, we show these to the user so they can select the correct one.
3. Activity Tracking (Notes / Interactions)
We need to be able to create and optionally update activity records (e.g. notes) against CRM entities to reflect phone calls and messages that happen via TalentLynk.
Required capabilities
CREATE / POST
Endpoint to create an activity record (e.g. Note / Interaction / Activity) linked to:
Candidate
Client contact
Company / Account (if supported)
The creation endpoint should support:
Reference to the related entity (e.g. candidate ID, contact ID, etc.)
Reference to the user/consultant (e.g. CRM user ID)
Date/time of the activity (if not automatically set)
Free-text description / body of the note
Optional activity type / category (e.g. phone call, SMS, WhatsApp, email)
UPDATE / PUT/PATCH
Endpoint to update an existing activity record, allowing modification of:
Text/body of the note
Activity type / category (if applicable)
How TalentLynk uses this
After each communication (call, SMS, WhatsApp, etc.), and based on each customer’s preferences, we will:
Create a simple activity record with date and time, or
Create a richer note including a short summary of the conversation (potentially AI-generated).
Users may later want to adjust the classification or wording of the note, so we need the ability to update:
The note text
The note type/category
4. Contextual Information & Metadata
We also need a few supporting endpoints that return metadata used by the other operations. This includes:
Users / Consultants
Endpoint to list CRM users (consultants, recruiters, etc.)
The response should include at minimum:
User ID (used when creating activities on their behalf)
Name
Email address (used for matching to TalentLynk user accounts)
How we use it
On connection, we fetch the list of users and match them to TalentLynk users by email.
We store the corresponding CRM user ID so that new notes/activities are created under the correct consultant in your system.
Activity / Note Types
Endpoint(s) to list available note/activity types or categories (e.g. “Phone Call”, “SMS”, “Interview”, etc.)
How we use it
When creating activity records, some CRMs require a valid note type.
We fetch your list of types and:
Present them in the TalentLynk UI for the customer to map / choose from, or
Store default mappings so we send a valid type ID with each activity we create.
5. Technical & Operational Considerations
While not strictly functional requirements, the following are important for a robust integration:
Authentication:
Server-to-server credentials (OAuth2 client credentials, API keys, or similar).
A way to obtain and refresh tokens programmatically (if applicable).
Rate limits:
Documented rate limits and guidance so we can implement appropriate backoff and throttling.
Environments:
Access to a sandbox / staging environment for development and testing.
Versioning & change management:
Stable, versioned endpoints, and a process to communicate breaking changes well in advance.
If your API supports the capabilities described above, it will be straightforward for us to build and maintain a high-quality integration for our mutual customers.
Please feel free to reach out with any questions or to share your API documentation so we can confirm details and next steps.
Thank you!