Sample Requests and Responses

Once you have an authentication token, you can test the API at https://apistgp.smashfly.com/ContactAPI/help (public staging environment) orhttps://api.smashfly.com/ContactAPI/help (production environment) and click Show Sample for any of the requests.

Sample Requests

Sample requests can include parameters that limit the contact records that are returned.

  • To retrieve contacts that were added to the system in July 2017:

    GET /v1/contacts/?contactDbId=1&fromAddedOn=2017-07-01&toAddedOn=2017-07-31

  • To retrieve contacts from a specific contact list who are in a status of “New” or “Engaged”:

    GET /v1/contacts/?contactDbId=1&contactListIds=999&globalStatuses=New|Engaged

  • To retrieve contacts from a specific contact list who are in a status of “Offer" or "Hired" and who were added to the system in August 2017:

    GET /v1/contacts/?contactDbId=1&contactListIds=999&globalStatuses=Offer|Hired&fromAddedOn=2017-08-01&toAddedOn=2017-08-31

  • To retrieve contacts who were deactivated or deleted in December 2018 and who are not flagged to be expunged from the system:

    GET /v1/contacts/expunged/?contactDbId=1&fromUpdatedOn=2018-12-01&toUpdatedOn=2018-12-31

  • To search for contacts with the first name Joe and the Last name Bloggs and retrieve their first name, last name, email and school from a specific contact database and Job/Event/Contact List:

    POST /v1/contacts/search

    Request JSON Body

    {

    "ContactDbId": 55,

    "Filter": [

    {

    "FieldName": "FirstName",

    "Value": ["Joe"],

    "Operator": "Equals"

    },

    {

    "FieldName": "FirstName",

    "Value": ["Bloggs"],

    "Operator": "Equals"

    }],

    "ListIds": [123456],

    "PageSize": 10,

    "PageNumber": 1,

    "VisibleFields": ["FirstName", "LastName", "Email", "School"]

    }

Sample Responses

Each API response includes metadata and a response body. The response body includes the following fields, including the results (contact records that met the query definition).

Property Description
code Status code of the HTTP response. The API will return an Accepted (202) response if the request succeeds. If an error occurs, it will include the error code.
message Brief message describing the result of the request.
limit Pagination limit used for the request.
offset Pagination offset used for the request.
total Total count of records matching the supplied parameters.
returned Count of records returned in the response.
results

Any resources to be returned; for example, a collection of contacts or a resume or set of resumes. For a list of fields that will be included in this section if they contain data when the record is exported, refer to Contact Fields.

See https://api.smashfly.com/ContactAPI/help for sample response code.

The search contacts response returns different meta data – as a result the fields returned are the following.

Property Description
code Status code of the HTTP response. The API will return an Accepted (202) response if the request succeeds. If an error occurs, it will include the error code.
message Brief message describing the result of the request.
PageNumber The number of the page requested
PageSize The pageSize set in the request
ContactsMatchingCriteria The number of contacts matching the search criteria
ContactsOnPage The number of contacts returned in this request
TotalContactsCount

The total number of contacts

NumberOfPages The number of pages of contacts for this search criteria

Error Responses

For requests that result in an error, the corresponding response will specify a relevant HTTP status code, as well as pertinent error messaging describing the failure. Following are some examples of errors related to authentication and request validation.

Invalid Token Provided

{

"code": 401,

"message": "Unauthorized",

"errors": [

{

"message": "Access denied"

}

]

}

Request Validation Error

{

"code": 400,

"message": "Errors occurred validating the request",

"errors": [

{

"message": "Expecting a valid date in the form yyyy-mm-dd",

"field": "ToAddedOn"

},

{

"message": "Value is invalid, expecting delimited list of integers",

"field": "ContactListIds"

}

]

}