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.

  1. Applicable API Key Roles
  2. Authentication
  3. Available Services
    1. Retrieve or add contacts
    2. Get info for an individual contact
    3. Get contacts by tag
    4. Get current portal user’s contact record
  4. Request format
  5. Response format
  6. 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
Get current portal user’s contact record

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.