Contact list api

Product APIs

I would like to know if there are any APIs that would allow me to Get/Set a contact list. I’ll be writing a serveless app to do this but I’m fine with REST APIs.

I thought maybe GET /contacts/ would return lists but it does not based on REST API docs.

Likewide, I was hoping PUT /contacts/ would let me set a list property but I don’t see this property in the REST API docs.

I need to be able to put people into a list from a serveless app based on external events. I’m hoping someone konws how I might go about doing this.

1 Like

These are not the same as lists, are they?

I specifically need to add to list to facilitate a journey I’m creating.

2 Likes

Hi Steve,
Could you give it a try with Freshmarketer API Docs
Assuming you’re the customer of FCRM, and Freshsales public API does not have list functionality.

Thanks,
Teja Kummarikuntla

4 Likes

object

id

integer

The reference ID of your list.

required

name

string

The name of your list. Must be unique against all other list and segment names.

required

recipient_count

integer

The count of recipients currently in the list.

required

{ "id": 1, "name": "listname", "recipient_count": 0 }

object

errors

array[object]

message

string

field

string or null

the field that generated the error

help

object

helper text or docs for troubleshooting

{ "errors": [ { "field": "field_name", "message": "error message" } ] }

object

errors

array[object]

message

string

field

string or null

the field that generated the error

help

object

helper text or docs for troubleshooting

{ "errors": [ { "field": "field_name", "message": "error message" } ] }

After you've completed the steps in Get Ready to Use the People API you are ready to read and manage contacts.

The following code samples demonstrate how to send a few simple requests. For a full list of methods, see the reference documentation.

Important: Only contact based people can be modified. Profile based people read using resource name "people/me" or by an account ID can not be modified.

List the user's contacts

To get a list of people in the user's contacts, use the following code:

Protocol

GET /v1/people/me/connections?personFields=names,emailAddresses HTTP/1.1 Host: people.googleapis.com

Java

ListConnectionsResponse response = peopleService.people[].connections[].list["people/me"] .setPersonFields["names,emailAddresses"] .execute[]; List people = response.getConnections[];

Python

people = people_service.people[].connections[] .list['people/me', personFields='names,emailAddresses']

PHP

$people = $people_service->people_connections->listPeopleConnections[ 'people/me', array['personFields' => 'names,emailAddresses']];

.NET

PeopleResource.ConnectionsResource.ListRequest peopleRequest = peopleService.People.Connections.List["people/me"]; peopleRequest.PersonFields = "names,emailAddresses"; ListConnectionsResponse response = peopleRequest.Execute[]; IList people = response.Connections;

List the user's contacts that have changed

Java

// Initial request ListConnectionsResponse fullSyncResponse = peopleService.people[].connections[].list["people/me"] .setPersonFields["metadata,names,emailAddresses"] .setRequestSyncToken[true] .execute[]; // Fetch all the pages while [!fullSyncResponse.getNextPageToken[].isEmpty[]] { fullSyncResponse = peopleService.people[].connections[].list["people/me"] .setPersonFields["metadata,names,emailAddresses"] .setRequestSyncToken[true] .setPageToken[fullSyncResponse.getNextPageToken[]] .execute[]; } // Some time passes // Fetch incremental changes using the sync token returned in the last fullSyncResponse. try { ListConnectionsResponse incrementalSyncResponse = peopleService.people[].connections[].list["people/me"] .setPersonFields["metadata,names,emailAddresses"] .setSyncToken[fullSyncResponse.getNextSyncToken[]] .execute[]; for [Person person : incrementalSyncResponse.getConnections[]] { handlePerson[person]; } // Fetch all the pages while [!incrementalSyncResponse.getNextPageToken[].isEmpty[]] { incrementalSyncResponse = peopleService.people[].connections[].list["people/me"] .setPersonFields["metadata,names,emailAddresses"] .setSyncToken[fullSyncResponse.getNextSyncToken[]] .setPageToken[incrementalSyncResponse.getNextPageToken[]] .execute[]; for [Person person : incrementalSyncResponse.getConnections[]] { handlePerson[person]; } } } catch [GoogleJsonResponseException e] { if [e.getStatusCode[] == 410] { // Sync token expired. Make full sync request. } } void handlePerson[Person person] { if [person.getMetadata[].getDeleted[]] { // Handle deleted person } else { // Handle changed person } }

Note: Writes may have a propagation delay of several minutes for sync requests. Incremental syncs are not intended for read-after-write use cases.

More details about sync behavior at ListConnections.

Search the user's contacts

To search all of the user's contacts, use the following code:

Protocol

// Warmup cache GET /v1/people:searchContacts?query=&readMask=names,emailAddresses HTTP/1.1 Host: people.googleapis.com

// Send search request after several seconds GET /v1/people:searchContacts?query=query&readMask=names,emailAddresses HTTP/1.1 Host: people.googleapis.com

Java

// Warmup cache SearchResponse response = peopleService.people[].searchContacts[] .setQuery[""] .setReadMask["names,emailAddresses"] .execute[];

// Wait a few seconds Thread.sleep[5];

// Send search request SearchResponse response = peopleService.people[].searchContacts[] .setQuery["query"] .setReadMask["names,emailAddresses"] .execute[];

Important: Search uses a lazy cache that is updated after a request. Clients should first send a warmup search request with an empty query to make sure the cache has the latest data.Note: Search does a prefix match of the query with the fields on a person. For example, a person with name "foo name" matches queries such as "f", "fo", "foo", "foo n", "nam", etc., but not "oo n".

Create a new contact

To create a new contact, use the following code:

Protocol

POST /v1/people:createContact HTTP/1.1 Body: { "names": [{ "givenName": "John", "familyName": "Doe" }] } Host: people.googleapis.com

Java

Person contactToCreate = new Person[]; List names = new ArrayList[]; names.add[new Name[].setGivenName["John"].setFamilyName["Doe"]]; contactToCreate.setNames[names]; Person createdContact = peopleService.people[].createContact[contactToCreate].execute[];

Quota usage per request

• 1 Critical read requests [Contact and Profile Reads]
• 1 Critical write requests [Contact Creates and Updates]
• 1 Daily Contact Writes [Total]

Warning: Mutate requests for the same user should be sent sequentially to avoid increased latency and failures.

Update an existing contact

To update an existing contact, you must include the person.metadata.sources.etag field in the person for the contact to be updated to make sure the contact has not changed since your last read. Use the following code:

Protocol

PATCH /v1/resource_name:updateContact?updatePersonFields=emailAddresses HTTP/1.1 Body: { "resourceName": "resource_name", "etag": "etag", "emailAddresses": [{ "value": "" }], } Host: people.googleapis.com

Java

Person contactToUpdate = peopleService.people[].get["resource_name"].execute[]; List emailAddresses = new ArrayList[]; emailAddresses.add[new EmailAddress[].setValue[""]]; contactToUpdate.setEmailAddresses[emailAddresses]; Person updatedContact = peopleService.people[] .updateContact[contactToUpdate.getResourceName[], contactToUpdate] .setUpdatePersonFields["emailAddresses"] .execute[];

Quota usage per request

• 1 Critical read requests [Contact and Profile Reads]
• 1 Critical write requests [Contact Creates and Updates]
• 1 Daily Contact Writes [Total]

Warning: Mutate requests for the same user should be sent sequentially to avoid increased latency and failures.

Delete an existing contact

To delete an existing contact, use the following code:

Protocol

DELETE /v1/resource_name:deleteContact HTTP/1.1 Host: people.googleapis.com

Java

peopleService.people[].deleteContact["resource_name"].execute[];

Quota usage per request

• 1 Write requests [Contact Deletes and Contact Group Writes]

Warning: Mutate requests for the same user should be sent sequentially to avoid increased latency and failures.

Batch create new contacts

To batch create new contacts, use the following code:

Protocol

POST /v1/people:batchCreateContacts?readMask=names HTTP/1.1 Body: { "contacts": [ { "contactPerson": { "names": [ { "givenName": "John", "familyName": "Doe" } ] } } ] } Host: people.googleapis.com

Java

Person person1 = new Person[]; person1.setNames[ImmutableList.of[new Name[].setGivenName["John"].setFamilyName["Doe"]]]; ContactToCreate contactToCreate1 = new ContactToCreate[]; contactToCreate1.setContactPerson[person1]; Person person2 = new Person[]; person2.setNames[ImmutableList.of[new Name[].setGivenName["Bob"].setFamilyName["Dylan"]]]; ContactToCreate contactToCreate2 = new ContactToCreate[]; contactToCreate2.setContactPerson[person2]; BatchCreateContactsRequest request = new BatchCreateContactsRequest[]; request.setContacts[ImmutableList.of[contactToCreate1, contactToCreate2]].setReadMask["names"]; BatchCreateContactsResponse response = peopleService.people[].batchCreateContacts[request].execute[];

Quota usage per request

• 6 Critical read requests [Contact and Profile Reads]
• 6 Critical write requests [Contact Creates and Updates]
• 200 Daily Contact Writes [Total]

Warning: Mutate requests for the same user should be sent sequentially to avoid increased latency and failures.

Batch update existing contacts

To update an existing contact, you must include the person.metadata.sources.etag field in each person for the contact to be updated to make sure the contact has not changed since your last read. Use the following code:

Protocol

POST /v1/people:batchUpdateContacts?updateMask=names&readMask=names,emailAddresses HTTP/1.1 Body: { "contacts": { "resource_name": { "emailAddresses": [ { "value": "" } ] "etag": "etag" } } } Host: people.googleapis.com

Java

Person contactToUpdate = peopleService.people[].get["resource_name"].execute[]; contactToUpdate.setNames[ ImmutableList.of[new Name[].setGivenName["John"].setFamilyName["Doe"]]]; BatchUpdateContactsRequest request = new BatchUpdateContactsRequest[]; ImmutableMap map = ImmutableMap.of[contactToUpdate.getResourceName[], contactToUpdate]; request.setContacts[map].setUpdateMask["names"].setReadMask["names,emailAddresses"]; BatchUpdateContactsResponse response = peopleService.people[].batchUpdateContacts[request].execute[];

Quota usage per request

• 6 Critical read requests [Contact and Profile Reads]
• 6 Critical write requests [Contact Creates and Updates]
• 200 Daily Contact Writes [Total]

Warning: Mutate requests for the same user should be sent sequentially to avoid increased latency and failures.

Batch delete existing contacts

To batch delete existing contacts, use the following code:

Protocol

POST /v1/people:batchDeleteContacts HTTP/1.1 Body: {"resource_names": ["resource_name"]} Host: people.googleapis.com

Java

BatchDeleteContactsRequest request = new BatchDeleteContactsRequest[]; request.setResourceNames[ImmutableList.of[resource_name]]; peopleService.people[].batchDeleteContacts[request].execute[];

Quota usage per request

• 10 Write requests [Contact Deletes and Contact Group Writes]

Warning: Mutate requests for the same user should be sent sequentially to avoid increased latency and failures.