Contact Synchronization
Use Case Overview
Key Model(s) and Fields | Supported Applications |
---|---|
Contacts firstName lastName account emailAddress updatedTimestamp | Salesforce CRM, HubSpot, MS Dynamics CRM, Zoho CRM |
This is a bi-directional integration. In this example, you can GET, POST, PUT/PATCH and DELETE target resources to help users maintain a clean database.
How to build this use case with Alloy's Unified API
1. Create a Connection
To get started, you'll need to first implement Alloy's Unified API and create a connection. A connection represents each time an end user links an app to Alloy's Unified API. See Getting Started in our Unified API Quickstart.
If you’ve already done this, read on!
2. Sync historical contact data from a user's CRM to your application
The first step is to sync the existing contacts in your user's CRM to your application/database.
Call the [GET List Contacts]
endpoint to retrieve your desired list of contacts from the CRM. If you don’t want to sync every contact — for example, maybe you’re only interested in those created after a certain date — you can filter queries with parameters like createdTimestamp
and updatedTimestamp
.
curl --request GET \
--url 'https://embedded.runalloy.com/2023-06/one/crm/contacts?connectionId=CONNECTION_ID&createdTimestamp=1699347138' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'accept: application/json'
Your response payload should look something like this:
{
"contacts": [
{
"remoteId": "0000000000000000000",
"firstName": "Gregg",
"lastName": "Mojica",
"account": null,
"addresses": [],
"emailAddresses": [],
"phoneNumbers": [],
"lastActivityAt": null,
"createdTimestamp": 1699457138,
"updatedTimestamp": 1699457138,
"id": "b8f78a04-b00d-4192-ba4f-935a72ac6b4d"
},
{
"remoteId": "0000000000000000000",
"firstName": "Jonathan",
"lastName": "Lee",
"account": null,
"addresses": [
{
"country": "",
"street1": "",
"state": "",
"city": "",
"addressType": "mailing",
"postalCode": ""
}
],
"emailAddresses": [],
"phoneNumbers": [],
"lastActivityAt": null,
"createdTimestamp": 1684783618,
"updatedTimestamp": 1684783618,
"id": "c3d2c3po-l00r-8892-re7t-734f01fh90kl"
},
{
"remoteId": "0000000000000000000",
"firstName": "Dave",
"lastName": "Smith",
"account": null,
"addresses": [],
"emailAddresses": [],
"phoneNumbers": [],
"lastActivityAt": null,
"createdTimestamp": 1699486897,
"updatedTimestamp": 1699486897,
"id": "74g338fc-192h-2738-7384-23e44hgf9f87"
},
{
"remoteId": "0000000000000000000",
"firstName": "Viral",
"lastName": "Ruparel",
"account": null,
"addresses": [],
"emailAddresses": [],
"phoneNumbers": [],
"lastActivityAt": null,
"createdTimestamp": 1699518755,
"updatedTimestamp": 1699518755,
"id": "3827501c-87g7-3g39-72fc-hfd775dhc716"
}
]
}
As you can see, your response payload will match the structure of Alloy’s common model for Contacts, rather than the structure of the source application (Salesforce, HubSpot, Dynamics or Zoho).
From here, you can write the app logic to sync the contacts to your application’s database.
3. Writing contacts to your user's CRM
Use the [POST Create Contact]
endpoint to write new contacts that are generated in your application to your user's CRM. You can also choose and filter by a unique identifier to avoid the creation of duplicate records — some of which include:
emailAddress
id
createTimestamp
Here's what the request looks like:
curl --request POST \
--url 'https://embedded.runalloy.com/2023-06/one/crm/contacts?connectionId=CONNECTION_ID' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"lastName": "Lee",
"firstName": "Jon",
"account": null,
"emailAddresses": [
{
"emailAddress": "jon@jon.com",
"emailAddressType": "Main"
}
],
"phoneNumbers": [
{
"phoneNumberType": "Cell",
"phoneNumber": "(111)222-3333"
}
]
}
'
And here's the example response:
{
"contact": {
"remoteId": "003Hs00004kyNdFIAU",
"firstName": "Jon",
"lastName": "Lee",
"account": null,
"addresses": [],
"emailAddresses": [],
"phoneNumbers": [
{
"phoneNumberType": "Phone",
"phoneNumber": "(111)222-3333"
}
],
"lastActivityAt": null,
"createdTimestamp": 1699561896,
"updatedTimestamp": 1699561896,
"id": "6a47a18f-3506-43f4-806d-08d567bdc50b"
}
}
4. Updating existing contacts
To update existing Contacts, use the PUT Update Contacts
endpoint to generate a request that looks like this:
curl --request PUT \
--url 'https://embedded.runalloy.com/2023-06/one/crm/contacts/12?connectionId=CONNECTION_ID' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"firstName": "Joe",
"lastName": "Smith",
"emailAddresses": [
{
"emailAddressType": "Main",
"emailAddress": "joe.smith@joesmith.com"
}
]
}
'
In both cases, the Contacts you write will be structured using Alloy’s common model.
Ensure that users have accurate contact data
By ensuring that contact data flows smoothly between your product and a user’s CRM, you can ensure that they’re always working with the most up-to-date information and creating the personalized experiences their customers expect.