Contacts
This documentation has moved to the Spark Platform website. Please click here to view.
The Contacts API allows retrieval of contact data for a user as well as creation of a new contact record.
- Applicable API Key Roles
- Authentication
- Available Services
- Request format
- Response format
- Supported fields
Applicable API Key Roles
This service is available to API keys with IDX roles with IDX permissions; it is not available to IDX roles with portal permissions. More information about roles may be found here.
Authentication
Requests must be authenticated according to these instructions or HTTP 401 (Unauthorized) will be returned.
Available Services
Retrieve or add contacts
URI: /<API Version>/contacts
HTTP Method | Description | Request Notes | Response Notes |
---|---|---|---|
GET | Retrieve information about desired contacts for the current user if authorization level allows | No parameters. If not permitted, returns HTTP 403 (Forbidden). | Returns the Contact Response Format. |
POST | Add a contact | To add a contact, POST to /<API Version>/contacts with Content-Type: application/json . The POST body must use the Contact Request Format. | The standard success/fail response format is returned after the request is sent. |
PUT,DELETE | Returns HTTP 405 (Method Not Allowed) | Not implemented | Not implemented |
Get info for an individual contact
URI: /<API Version>/contacts/XX
XX is the ID of the contact
HTTP Method | Description | Request Notes | Response Notes |
---|---|---|---|
GET | Retrieves information about an individual contact. | No parameters | Returns the Contact Response Format. |
POST,PUT,DELETE | Returns HTTP 405 (Method Not Allowed) | Not implemented | Not implemented |
Get contacts by tag
URI: /<API Version>/contacts/tags/XX
XX is the tag name (e.g. Web Leads, Hot Prospects, etc.)
HTTP Method | Description | Request Notes | Response Notes |
---|---|---|---|
GET | Returns all contacts that match the particular tag. | No parameters | Returns the Contact Response Format. |
POST,PUT,DELETE | Returns HTTP 405 (Method Not Allowed) | Not implemented | Not implemented |
URI: /<API Version>/my/contact
Note: this is available only for API keys with IDX roles that have authenticated via OAuth to obtain portal permissions.
HTTP Method | Description | Request Notes | Response Notes |
---|---|---|---|
GET | Returns the current portal user’s contact record, if the current API key has an IDX role and has authenticated using OAuth to obtain portal permissions. | No parameters | Returns the Contact Response Format for the current portal user’s contact record. |
POST,PUT,DELETE | Returns HTTP 405 (Method Not Allowed) | Not implemented | Not implemented |
Contact Response Format
This is the format in which contact data is returned from the flexmls API. Responses are paginated using the standard pagination syntax.
{ "D": { "Success": true, "Results": [ { "ResourceUri": "/vX/contacts/201010122342756895000000", "Id": "201010122342756895000000", "DisplayName": "Some Person", "PrimaryEmail": "test@test.com", "Tags": [ "IDX Lead" ] } ] } }
Contact Request Format
This is used for sending contact information to the flexmls API. Primary differences from the response format include: 1) The “Results” attribute is named “Contacts”; and 2) server-generated data is omitted.
{ "D": { "Contacts": [ { "DisplayName": "Some Person", "PrimaryEmail": "test@test.com" } ] } }
Supported Fields
Below is a list of fields supported by this service.
Name | Required on POST /contacts | Field Supported On POST /contacts | Description | Notes |
---|---|---|---|---|
DisplayName | Yes | Yes | String with the name of the contact | Max of 75 characters. |
PrimaryEmail | No | Yes | Strings with the primary e-mail address | Max of 75 characters. |
SecondaryEmails | No | An array containing one or more strings the secondary e-mail addresses | ||
GivenName | No | String with the first (given) name of the contact | ||
MiddleName | No | String with the middle name of the contact | ||
FamilyName | No | String with the last (family) name of the contact | ||
SpouseGivenName | No | String with the contact’s spouse’s first (given) name | ||
SpouseMiddleName | No | String with the contact’s spouse’s middle name | ||
SpouseFamilyName | No | String with the contact’s spouse’s last (family) name | ||
PrimaryPhoneNumber | No | Yes | String with a primary phone number | |
HomePhoneNumber | No | String with a home phone number | ||
WorkPhoneNumber | No | String with a work (office) phone number | ||
FaxPhoneNumber | No | String with a fax phone number | ||
MobilePhoneNumber | No | String with a mobile phone number | ||
PagerPhoneNumber | No | String with a pager number | ||
OtherPhoneNumber | No | String with an “other” phone number | ||
HomeStreetAddress | No | Yes | String with the first and second line of the home address | First and second lines are separated by \n . If there is no second line, the \n is omitted. |
HomeLocality | No | Yes | String with the locality (city) for the home address | |
HomeRegion | No | Yes | String with the region (state) for the home address | |
HomePostalCode | No | Yes | String with the home postal code (zip code) | |
WorkStreetAddress | No | String with the first and second line of the work (office) address | First and second lines are separated by \n . If there is no second line, the \n is omitted. | |
WorkLocality | No | String with the locality (city) for the work (office) address | ||
WorkRegion | No | String with the region (state) for the work (office) address | ||
WorkPostalCode | No | String with the work (office) postal code (zip code) | ||
Organization | No | String with the contact’s organization name | ||
Position | No | String with the contact’s position | ||
Birthday | No | String with the contact’s birthday | ||
Anniversary | No | String with the contact’s anniversary | ||
Assistant | No | String with the contact’s assistant | ||
Children | No | String with the contact’s children | ||
Status | No | String with the contact’s marital status | ||
Other | No | An array with one or more strings with other contact information that doesn’t fit elsewhere | ||
Pets | No | String with the contact’s pets | ||
ReferredBy | No | String with the name of the person who referred the contact | ||
Salutation | No | String with the contact’s salutation | ||
Tag | No | Yes | An array containing one or more strings representing tag names | A tag is stored as a contact group in flexmls. Useful for grouping leads according to source, i.e. leads from one website could be put into one group, and leads from another website could be put in a different group. |
Notify | No | Yes | true or false | Defaults to false. If true, will send a message to the owner of the contact stating that a new contact has been added, showing the contact’s information (name, email, etc.) and providing a direct link to view the lead inside of flexmls. Note that this attribute is not returned with a GET request. |
Comments on this entry are closed.