Wealthbox CRM API

Introduction¶

The Wealthbox API consists of REST-based resource URLs which provide a predictable way to interact with Wealthbox over JSON or XML.

We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application.

The Wealthbox API gives you powerful read/write access to your CRM account data, allowing you to build integrations with your other preferred tools.

API Endpoint

https://api.crmworkspace.com

Authentication¶

Every request to the Wealthbox CRM needs to be identified and authorized. In order to do this, you must provide API credentials, which can take the form of an API access token, provided inside your personal settings, or by leveraging our OAuth 2.0 authentication flow.

Authenticating with a personal API access token

Personal API access tokens are reserved for building personal integrations — such as those to in-house systems — and testing integration capabilities. If you are a current or future integration partner who makes your app available to mutual customers, authenticating with OAuth is required for co-marketing and release.

Authenticate your account when using the API by including an API access token in the request header. In order to obtain a new access token or to manage your existing tokens, please visit the API access token settings page. From there, simply click 'Create Access Token' and give the token a name. That token should then be passed as an HTTP Header, with the name ACCESS_TOKEN, in all requests to the API.

Authenticating with OAuth

The Wealthbox API allows authenticating with OAuth 2.0 using authorization code grants as well as refresh token grants as defined in RFC6749. Authorization is scoped to individual users (who may have different permissions from one another) rather than organizations.

To begin, you’ll need to register so we can issue a client ID and client secret which will uniquely identify your application to us. The client ID is a public value which will be exposed when the authorization flow begins in the user’s browser. The client secret, though, will be known only to you and us and is used to verify your identity. You will need to store it safely. If your client secret is compromised, please contact us immediately so we can deactivate it and issue a replacement.

To implement OAuth for your application, please email support@wealthbox.com with your request and details about your application.

The basic flow of OAuth is as follows:

Most of the following information is about OAuth 2.0 in general and isn’t unique to Wealthbox, in the examples below, we’ll use placeholder values forclient_id, client_secretandredirect_uriwhich you’ll need to replace with your unique values.

The code grant flow begins in a user’s browser. You should navigate them tohttps://app.crmworkspace.com/oauth/authorizewith the following query parameters appended to the URL:

# Parameters
client_id     => required
redirect_uri  => required(must match the URI that was registered)
response_type => required(only "code" authorization flow supported)
scope         => optional(available scopes are (login, data) login is default if not included)

# Example GET
https://app.crmworkspace.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=CALLBACK_URL&response_type=code&scope=login+data

If the user isn’t currently logged in to their Wealthbox account, they’ll be prompted for their Wealthbox credentials first.
After entering their credentials, the user will be shown an authorization page to grant your application access to the Wealthbox API on their behalf.
After the user has granted access, the browser will navigate to your redirect URI. This will include the authorization code in the query string.

Your application can then exchange the authorization code for an access token via POST tohttps://app.crmworkspace.com/oauth/tokenwith anapplication/x-www-form-urlencodedpayload (like query parameters, but in the body instead of the URL). This should occur immediately as the authorization code has a brief lifetime.

# Parameters
client_id     => required
client_secret => required
code          => required(the code value which was included with the redirect)
grant_type    => required(only "authorization_code" supported)
redirect_uri  => required(must match the URI that was registered)

# Example POST
POST /oauth/token HTTP/1.1
Host: app.crmworkspace.com
Accept: application/json
Content-Length: 255
Content-Type: application/x-www-form-urlencoded
https://app.crmworkspace.com/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=CODE&grant_type=authorization_code&redirect_uri=CALLBACK_URL

# Example Response (application/json)
{
 "access_token":"de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
 "created_at":10588285800,
 "expires_in":7200,
 "refresh_token":"8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",
 "scope":"login data",
 "token_type":"Bearer"
}

Currently, eachaccess_tokenlives for two hours. Therefresh_tokenlives for 90 days.
If your access token expires, you will need to use the refresh token to POST tohttps://app.crmworkspace.com/oauth/token. This is similar to step 5 exceptgrant_typemust be set to "refresh_token"
```
# Parameters
client_id     => required
client_secret => required
grant_type    => required(must be "refresh_token")
refresh_token => required(the previously obtained refresh_token value)
```
If your refresh token has expired, you will need to start the process over from step 1. We recommend that apps autonomously connect to Wealthbox CRM using the refresh token, within the 90 day window, if they want to avoid forcing the user to reauthenticate.

Example Request with API access token

$ curl https://api.crmworkspace.com/v1/contacts -i \
-H "ACCESS_TOKEN:12345678901234567890123456789012"

Example Request with OAuth access token

$ curl https://api.crmworkspace.com/v1/contacts -i \
-H "AUTHORIZATION: Bearer 12345678901234567890123456789012"

Errors¶

Wealthbox uses standard HTTP response codes to indicate the status of an API request. Generally, 2xx response codes indicate success, 4xx represents a problem that occurred (e.x., authentication token was not included in request, or required fields were not present to create a "contact"). 5xx codes indicate there was an error on the server, even though your request appears valid.

HTTP Status Code Summary

200 - OK	Everything worked as expected.
201 - Authorization token created	After a successful authorization via the API, an access token was created.
202 - Two-Factor Authentication required	After a successful authorization via the API, Two-Factor authentication is required.
400 - Bad Request	The request could not be understood by the server due to malformed syntax.
401 - Unauthorized	No valid API key provided.
402 - Trial expired	Your Wealthbox trial account has expired.
403 - Inaccessible	The requesting user does not have permission to view the resource.
404 - Not Found	The requested item doesn't exist.
422 - Invalid request parameters	Your request was invalid and rejected by the server.
422 - Unprocessable Entity	The content-type in the header may be invalid or the object sent doesn't match the content-type that was set.
429 - Too Many Requests	Too many requests hit the API too quickly.
5xx - Server Errors	Wealthbox error (Rare occurrence.)

Pagination¶

All resources in the API have support for fetching in bulk via the list methods. For example, you could list all contacts, or all notes in your workspace.

We utilize a page-based system for listing items in bulk. This requires both per_page and a page parameter to be passed when fetching paginated data (see below).

Pagination Parameters

per_page number: 25 (default)
page number: 1 (default)

Example Request

$ curl https://api.crmworkspace.com/v1/contacts?per_page=50&page=2 -i \
-H "ACCESS_TOKEN:12345678901234567890123456789012"

Responses from the API¶

Each request made to the API will generate a JSON or XML response. The responses can be classified into 3 distinct types.

Successful response returning a single resource

When returning a single resource, the object is represented as a JSON object of its properties.

Successful response returning a collection of resources

When returning a collection of resources, the collection is returned as a JSON object, whose key is the plural version of the resource, for example /v1/contacts returns a JSON object whose key is contacts. The object contains an array of the resources stored at that key. It is important to remember that these collections are not ordered, so their order can not be counted on.

Unsuccessful response

When a request is unsuccessful the API will return a JSON object with 2 keys, success,which will be set to false and an errors key which describes the error.

Versioning¶

When we make backwards-incompatible changes to the API we will release a new version. Examples of a backwards-compatible change that would not result in a new version would be adding a new endpoint, changing the order of properties in an API response, or adding a new optional property to an existing endpoint.

The current API version is v1, so any requests should include this in the URL.

Example Request

$ curl https://api.crmworkspace.com/v1/contacts -i \
-H "ACCESS_TOKEN:12345678901234567890123456789012"

Throttling¶

All requests made to the Wealthbox API are subject to throttling based on the API access token being used to make the request. The throttling rate is one request/second over a five minute sampling period, although, the Wealthbox API will permit short bursts of activity above that threshold. If you have made more requests to the Wealthbox API than permitted a 429 status code is returned to indicate that you have exceeded our rate limit for that period.

Retrieve login profile information¶

GET
Retrieve login profile information
`/v1/me`

This endpoint will return information about the user’s login profile.

Response Attributes

id number: The id of the user’s login profile
name string: The name associated with the login profile
first_name string: The first name associated with the login profile
last_name string: The last name associated with the login profile
email string: The email associated with the login profile
plan string: The subscribed plan of the login profile
created_at Datetime: A timestamp representing when the login profile was created
updated_at Datetime: A timestamp for when the login profile was last updated
current_user AccountUser: The user that is authorized with the API token used. All API calls with this token will be performed in this user’s account (workspace)
accounts Array (Account): An array of accounts (workspaces) that the user’s login profile has access to
users Array (AccountUser): An array of users associated with the login profile

Response 200

Body

{
  "id": 1,
  "name": "Bill Jones",
  "first_name": "Bill",
  "last_name": "Jones",
  "email": "bill@example.com",
  "plan": "premier",
  "created_at": "2015-05-24 10:00 AM -0500",
  "updated_at": "2015-10-12 11:30 PM -0500",
  "current_user": {
    "id": 1,
    "email": "bill@example.com",
    "name": "Bill Jones",
    "account": 1
  },
  "accounts": [
    {
      "id": 1,
      "name": "ABC Financial",
      "created_at": "2015-05-24 10:00 AM -0500"
    }
  ],
  "users": [
    {
      "id": 1,
      "email": "bill@example.com",
      "name": "Bill Jones",
      "account": 1
    }
  ]
}

Retrieve activity stream¶

GET
Retrieve activity stream
`/v1/activity{?contact}`

This endpoint will return all of the activity stream items for the user who has authenticated with their access token.

Parameters

contact number: The id of the Contact whose stream items you are requesting
cursor string: Use cursor to retrieve the next page of stream items. Page-based activity stream pagination is deprecated and will be removed in a later Wealthbox API version.

Response Attributes

stream_items Array (StreamItem)

Response 200

Body

{
  "stream_items": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "body": "Spoke with Kevin Anderson on the phone...",
      "linked_to": {
        "id": 1,
        "type": "Contact",
        "name": "Kevin Anderson"
      },
      "icon": "https://example.com/icon.png"
    }
  ]
}

Retrieve all contacts¶

GET
Retrieve all contacts
`/v1/contacts{?id}{?contactType}{?email}{?phone}{?type}{?name}{?active}{?householdTitle}{?order}{?tags}{?deleted}`

When fetching contacts, results can optionally be filtered by the following parameters. The parameters that can be used are listed below and can be used individually or in any combination.

Parameters

id number: The ID of the contact that you are searching for
contactType string: The contact_type of the Contact that should be returned from the endpoint
name string: The name that you wish to search for. This field supports partial matches, and searches all of the following name fields: prefix, first name, middle name, last name, suffix, nickname, and full name (for Households, Companies, and Trusts)
email string: The email address you wish to filter the contacts by
phone string: The phone number you wish to filter the contacts by, you may include any delimiters you would like ( -, (), they will be stripped on the server before matching
active boolean: Only returns contacts whose active flag match the specified value
tags array[string]: Only returns contacts with one of the specified tags
deleted boolean: Returns deleted items for this endpoint with attributes for id and deleted_at
householdTitle string: The household title you wish to filter the household title

Choices: HeadSpouseParentOther DependentChildSiblingPartnerGrandchildGrandparent
type string: The type of the Contact that should be returned from the endpoint

Choices: personhouseholdorganizationtrust
order string: The order that the contacts should be returned in

Choices: ascdescrecentcreatedupdated

Response Attributes

contacts Array (Contact)

Response 200

Body

{
  "contacts": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "prefix": "Mr.",
      "first_name": "Kevin",
      "middle_name": "James",
      "last_name": "Anderson",
      "suffix": "M.D.",
      "nickname": "Kev",
      "job_title": "CEO",
      "company_name": "Acme Co.",
      "twitter_name": "kev.anderson",
      "linkedin_url": "linkedin.com/in/kanderson",
      "background_information": "Met Kevin at a conference.",
      "birth_date": "1975-10-27",
      "anniversary": "1998-11-29",
      "client_since": "2002-05-21",
      "date_of_death": "2018-01-21",
      "assigned_to": 1,
      "referred_by": 1,
      "type": "Person",
      "gender": "Female",
      "contact_source": "Referral",
      "contact_type": "Client",
      "status": "Active",
      "marital_status": "Married",
      "attorney": 1,
      "cpa": 1,
      "doctor": 1,
      "insurance": 1,
      "business_manager": 1,
      "family_officer": 1,
      "assistant": 1,
      "other": 1,
      "trusted_contact": 1,
      "important_information": "Has 3 kids in college",
      "personal_interests": "Skiing: Downhill, Traveling",
      "investment_objective": "Aggressive Growth",
      "time_horizon": "Short Term",
      "risk_tolerance": "Low",
      "mutual_fund_experience": 3,
      "stocks_and_bonds_experience": 2,
      "partnerships_experience": 1,
      "other_investing_experience": 5,
      "gross_annual_income": 100000,
      "assets": 250000,
      "non_liquid_assets": 50000,
      "liabilities": 50000,
      "adjusted_gross_income": 75000,
      "estimated_taxes": 18000,
      "confirmed_by_tax_return": true,
      "tax_year": 2015,
      "tax_bracket": 10,
      "birth_place": "New York, NY",
      "maiden_name": "Anderson",
      "passport_number": "AB1234CD5689",
      "green_card_number": "ZX567HG134",
      "occupation": {
        "name": "CEO",
        "start_date": "2015-11-25"
      },
      "drivers_license": {
        "number": "1111111",
        "state": "New York",
        "issued_date": "2001-10-27",
        "expires_date": "2011-10-27"
      },
      "retirement_date": "2025-09-30",
      "signed_fee_agreement_date": "2013-05-15",
      "signed_ips_agreement_date": "2014-03-12",
      "signed_fp_agreement_date": "2015-03-12",
      "last_adv_offering_date": "2013-09-21",
      "initial_crs_offering_date": "2012-09-21",
      "last_crs_offering_date": "2013-09-21",
      "last_privacy_offering_date": "2011-10-23",
      "household": {
        "name": "The Anderson's",
        "title": "Head",
        "id": 1,
        "members": [
          {
            "id": 1,
            "first_name": "Kevin",
            "last_name": "Anderson",
            "title": "Head",
            "type": "Person"
          }
        ]
      },
      "image": "https://app.crmworkspace.com/avatar.png",
      "tags": [
        {
          "id": 1,
          "name": "Clients"
        }
      ],
      "street_addresses": [
        {
          "street_line_1": "155 12th Ave.",
          "street_line_2": "Apt 3B",
          "city": "New York",
          "state": "New York",
          "zip_code": "10001",
          "country": "United States",
          "principal": true,
          "kind": "Work",
          "id": 1,
          "address": "155 12th Ave., Apt 3B, New York, New York 10001, United States"
        }
      ],
      "email_addresses": [
        {
          "id": 1,
          "address": "kevin.anderson@example.com",
          "principal": true,
          "kind": "Work"
        }
      ],
      "phone_numbers": [
        {
          "id": 1,
          "address": "(555) 555-5555",
          "principal": true,
          "extension": "77",
          "kind": "Work"
        }
      ],
      "websites": [
        {
          "id": 1,
          "address": "https://www.example.com",
          "principal": true,
          "kind": "Website"
        }
      ],
      "custom_fields": [
        {
          "id": 1,
          "name": "My Field",
          "value": "123456789",
          "document_type": "Contact",
          "field_type": "single_select"
        }
      ],
      "contact_roles": [
        {
          "id": 1,
          "name": "Planning Advisor",
          "value": 1,
          "assigned_to": {
            "id": 1,
            "type": "User",
            "name": "Kevin Anderson"
          }
        }
      ]
    }
  ]
}

Create a new contact¶

POST
Create a new contact
`/v1/contacts`

Create a new Contact.

Request Attributes

prefix string: The preferred prefix for the Contact
first_name string, required: The first name of the Contact
middle_name string: The middle name of the Contact
last_name string, required: The last name of the Contact
suffix string: The suffix associated with the Contact
nickname string: A preferred shortname for the Contact
job_title string: The title the contact holds at his/her present company
company_name string: The name of the contact’s present company
twitter_name string: The twitter handle of the contact
linkedin_url string: The LinkedIn url for the contact
background_information string: A brief description of the contact in a longer format
birth_date Date: The birthdate of the contact
anniversary Date: The wedding anniversary of the contact
client_since Date: The date when the contact became a client
date_of_death Date: The date of death of the contact
assigned_to number: The id of the User who is assigned to this contact
referred_by number: The id of the Contact who referred this Contact to the firm
type string: The type of the Contact being created

Choices: Person Household Organization Trust
gender string: The gender of the Contact

Choices: Female Male Non-binary Unknown
contact_source string: The method in which this contact was taken on as new business

Choices: Referral Conference Direct Mail Cold Call Other
contact_type string: A string further classifying the Contact

Choices: Client Past Client Prospect Vendor Organization
status string: A flag indicating whether or not the contact is currently active

Choices: Active Inactive
marital_status string: The marital status of the contact

Choices: Married Single Divorced Widowed Life Partner Separated Unknown
attorney number: The id of the Contact acting as this Contact’s attorney
cpa number: The id of the Contact acting as this Contact’s accountant
doctor number: The id of the Contact acting as this Contact’s doctor
insurance number: The id of the Contact acting as this Contact’s insurance agent
business_manager number: The id of the Contact acting as this Contact’s business manager
family_officer number: The id of the Contact acting as this Contact’s family officer
assistant number: The id of the Contact acting as this Contact’s assistant
other number: The id of the Contact acting as this Contact’s other
trusted_contact number: The id of the Contact acting as this Contact’s trusted contact
important_information string: A block of text containing any other important info for the Contact
personal_interests string: A block of text containing personal interests for the Contact
investment_objective string: A basic classification of the Contact’s investment objectives

Choices: Aggressive Growth Growth Income Safety of Principal
time_horizon string: A basic classification of the time horizon for the Contact’s investment goals

Choices: Short Term Intermediate Long Term
risk_tolerance string: A basic classification of the Contact’s risk tolerance

Choices: Low Moderate High Risk
mutual_fund_experience number: Years of experience the contact has in the mutual fund market
stocks_and_bonds_experience number: Years of experience the contact has in the stocks and bonds fund market
partnerships_experience number: Years of experience the contact has in partnerships
other_investing_experience number: Years of experience the contact has in other aspects of the investment world
gross_annual_income number: The Contact’s estimated gross annual income
assets number: The value of all of the Contact’s holdings
non_liquid_assets number: The value of all of the Contact’s holdings that are illiquid
liabilities number: The total value of the Contact’s liabilities
adjusted_gross_income number: The Contact’s annual income adjusted for tax withholdings
estimated_taxes number: The total amount of taxes paid by the Contact during a tax year
confirmed_by_tax_return boolean: Flag to indicate if the Contact’s adjusted gross income and estimated taxes have been confirmed by their tax return
tax_year number: The year of the tax return that was used to confirm the Contact’s income and tax liability
tax_bracket number: Tax bracket that the Contact sits in according to his last recorded tax return
birth_place string: The city/state where the Contact was born
maiden_name string: The maiden name of the Contact is she has one
passport_number string: The passport number of the Contact
green_card_number string: The green card number of the Contact
occupation Occupation: An object representing critical information about the contact’s occupation
drivers_license DriversLicense: An object representing the contact’s driver’s license
retirement_date Date: The date when the Contact hope to retire
signed_fee_agreement_date Date: The date when the Contact’s fee agreement was signed
signed_ips_agreement_date Date: The date when the Contact’s IPS agreement was signed
signed_fp_agreement_date Date: The date when the Contact’s FP agreement was signed
last_adv_offering_date Date: The date when the Contact’s was last offered ADV
initial_crs_offering_date Date: The date when the Contact’s was initially offered CRS
last_crs_offering_date Date: The date when the Contact’s was last offered CRS
last_privacy_offering_date Date: The date when the Contact last signed their privacy agreement
company string: The name of the company the person is employed with
household HouseholdRequest: An object representing the contact’s household
tags Array (string): An array of tags that are associated with the contact
street_addresses Array (MailingAddressRequest): An array of the street addresses associated with the contact
email_addresses Array (EmailAddressRequest): An array of the email addresses associated with the contact
phone_numbers Array (PhoneNumberRequest): An array of the phone numbers associated with the contact
websites Array (WebsiteRequest): An array of the websites associated with the contact
custom_fields Array (CustomFieldRequest): An array of custom fields for this object
contact_roles Array (ContactRoleValueRequest): An array of contact roles for this contact, with their assigned options
visible_to string: The user group which is able to view the resource being created

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
prefix string: The preferred prefix for the Contact
first_name string, required: The first name of the Contact
middle_name string: The middle name of the Contact
last_name string, required: The last name of the Contact
suffix string: The suffix associated with the Contact
nickname string: A preferred shortname for the Contact
job_title string: The title the contact holds at his/her present company
company_name string: The name of the contact’s present company
twitter_name string: The twitter handle of the contact
linkedin_url string: The LinkedIn url for the contact
background_information string: A brief description of the contact in a longer format
birth_date Date: The birthdate of the contact
anniversary Date: The wedding anniversary of the contact
client_since Date: The date when the contact became a client
date_of_death Date: The date of death of the contact
assigned_to number: The id of the User who is assigned to this contact
referred_by number: The id of the Contact who referred this Contact to the firm
type string: The type of the Contact being created

Choices: Person Household Organization Trust
gender string: The gender of the Contact

Choices: Female Male Non-binary Unknown
contact_source string: The method in which this contact was taken on as new business

Choices: Referral Conference Direct Mail Cold Call Other
contact_type string: A string further classifying the Contact

Choices: Client Past Client Prospect Vendor Organization
status string: A flag indicating whether or not the contact is currently active

Choices: Active Inactive
marital_status string: The marital status of the contact

Choices: Married Single Divorced Widowed Life Partner Separated Unknown
attorney number: The id of the Contact acting as this Contact’s attorney
cpa number: The id of the Contact acting as this Contact’s accountant
doctor number: The id of the Contact acting as this Contact’s doctor
insurance number: The id of the Contact acting as this Contact’s insurance agent
business_manager number: The id of the Contact acting as this Contact’s business manager
family_officer number: The id of the Contact acting as this Contact’s family officer
assistant number: The id of the Contact acting as this Contact’s assistant
other number: The id of the Contact acting as this Contact’s other
trusted_contact number: The id of the Contact acting as this Contact’s trusted contact
important_information string: A block of text containing any other important info for the Contact
personal_interests string: A block of text containing personal interests for the Contact
investment_objective string: A basic classification of the Contact’s investment objectives

Choices: Aggressive Growth Growth Income Safety of Principal
time_horizon string: A basic classification of the time horizon for the Contact’s investment goals

Choices: Short Term Intermediate Long Term
risk_tolerance string: A basic classification of the Contact’s risk tolerance

Choices: Low Moderate High Risk
mutual_fund_experience number: Years of experience the contact has in the mutual fund market
stocks_and_bonds_experience number: Years of experience the contact has in the stocks and bonds fund market
partnerships_experience number: Years of experience the contact has in partnerships
other_investing_experience number: Years of experience the contact has in other aspects of the investment world
gross_annual_income number: The Contact’s estimated gross annual income
assets number: The value of all of the Contact’s holdings
non_liquid_assets number: The value of all of the Contact’s holdings that are illiquid
liabilities number: The total value of the Contact’s liabilities
adjusted_gross_income number: The Contact’s annual income adjusted for tax withholdings
estimated_taxes number: The total amount of taxes paid by the Contact during a tax year
confirmed_by_tax_return boolean: Flag to indicate if the Contact’s adjusted gross income and estimated taxes have been confirmed by their tax return
tax_year number: The year of the tax return that was used to confirm the Contact’s income and tax liability
tax_bracket number: Tax bracket that the Contact sits in according to his last recorded tax return
birth_place string: The city/state where the Contact was born
maiden_name string: The maiden name of the Contact is she has one
passport_number string: The passport number of the Contact
green_card_number string: The green card number of the Contact
occupation Occupation: An object representing critical information about the contact’s occupation
drivers_license DriversLicense: An object representing the contact’s driver’s license
retirement_date Date: The date when the Contact hope to retire
signed_fee_agreement_date Date: The date when the Contact’s fee agreement was signed
signed_ips_agreement_date Date: The date when the Contact’s IPS agreement was signed
signed_fp_agreement_date Date: The date when the Contact’s FP agreement was signed
last_adv_offering_date Date: The date when the Contact’s was last offered ADV
initial_crs_offering_date Date: The date when the Contact’s was initially offered CRS
last_crs_offering_date Date: The date when the Contact’s was last offered CRS
last_privacy_offering_date Date: The date when the Contact last signed their privacy agreement
company_name string: The name of the company the person is employed with
household Household: An object representing the contact’s household
image string: A expiring URL that links to the headshot for the contact valid for 7 days
tags Array (Tag): An array of tags that are associated with the contact
street_addresses Array (MailingAddress): An array of the street addresses associated with the contact
email_addresses Array (EmailAddress): An array of the email addresses associated with the contact
phone_numbers Array (PhoneNumber): An array of the phone numbers associated with the contact
websites Array (Website): An array of the websites associated with the contact
custom_fields Array (CustomField): An array of custom fields for this object
contact_roles Array (ContactRoleValue): An array of contact roles for this contact, with their assigned options

Request

Body

{
  "prefix": "Mr.",
  "first_name": "Kevin",
  "middle_name": "James",
  "last_name": "Anderson",
  "suffix": "M.D.",
  "nickname": "Kev",
  "job_title": "CEO",
  "company_name": "Acme Tech",
  "twitter_name": "kev.anderson",
  "linkedin_url": "linkedin.com/in/kanderson",
  "background_information": "Met Kevin at a conference.",
  "birth_date": "1975-10-27",
  "anniversary": "1998-11-29",
  "client_since": "2002-05-21",
  "date_of_death": "2018-01-21",
  "assigned_to": 1,
  "referred_by": 1,
  "type": "Person",
  "gender": "Female",
  "contact_source": "Referral",
  "contact_type": "Client",
  "status": "Active",
  "marital_status": "Married",
  "attorney": 1,
  "cpa": 1,
  "doctor": 1,
  "insurance": 1,
  "business_manager": 1,
  "family_officer": 1,
  "assistant": 1,
  "other": 1,
  "trusted_contact": 1,
  "important_information": "Has 3 kids in college",
  "personal_interests": "Skiing: Downhill, Traveling",
  "investment_objective": "Aggressive Growth",
  "time_horizon": "Short Term",
  "risk_tolerance": "Low",
  "mutual_fund_experience": 3,
  "stocks_and_bonds_experience": 2,
  "partnerships_experience": 1,
  "other_investing_experience": 5,
  "gross_annual_income": 100000,
  "assets": 250000,
  "non_liquid_assets": 50000,
  "liabilities": 50000,
  "adjusted_gross_income": 75000,
  "estimated_taxes": 18000,
  "confirmed_by_tax_return": true,
  "tax_year": 2015,
  "tax_bracket": 10,
  "birth_place": "New York, NY",
  "maiden_name": "Anderson",
  "passport_number": "AB1234CD5689",
  "green_card_number": "ZX567HG134",
  "occupation": {
    "name": "CEO",
    "start_date": "2015-11-25"
  },
  "drivers_license": {
    "number": "1111111",
    "state": "New York",
    "issued_date": "2001-10-27",
    "expires_date": "2011-10-27"
  },
  "retirement_date": "2025-09-30",
  "signed_fee_agreement_date": "2013-05-15",
  "signed_ips_agreement_date": "2014-03-12",
  "signed_fp_agreement_date": "2015-03-12",
  "last_adv_offering_date": "2013-09-21",
  "initial_crs_offering_date": "2012-09-21",
  "last_crs_offering_date": "2013-09-21",
  "last_privacy_offering_date": "2011-10-23",
  "company": "Acme Co.",
  "household": {
    "name": "The Anderson's",
    "title": "Head"
  },
  "tags": [
    "Clients"
  ],
  "street_addresses": [
    {
      "street_line_1": "155 12th Ave.",
      "street_line_2": "Apt 3B",
      "city": "New York",
      "state": "New York",
      "zip_code": "10001",
      "country": "United States",
      "principal": true,
      "kind": "Work",
      "destroy": false
    }
  ],
  "email_addresses": [
    {
      "address": "kevin.anderson@example.com",
      "principal": true,
      "kind": "Work",
      "destroy": false
    }
  ],
  "phone_numbers": [
    {
      "address": "(555) 555-5555",
      "principal": true,
      "extension": "77",
      "kind": "Work",
      "destroy": false
    }
  ],
  "websites": [
    {
      "address": "https://www.example.com",
      "principal": true,
      "kind": "Website",
      "destroy": false
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "value": "123456789"
    }
  ],
  "contact_roles": [
    {
      "id": 1,
      "value": 1
    }
  ],
  "visible_to": "Everyone"
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "prefix": "Mr.",
  "first_name": "Kevin",
  "middle_name": "James",
  "last_name": "Anderson",
  "suffix": "M.D.",
  "nickname": "Kev",
  "job_title": "CEO",
  "company_name": "Acme Co.",
  "twitter_name": "kev.anderson",
  "linkedin_url": "linkedin.com/in/kanderson",
  "background_information": "Met Kevin at a conference.",
  "birth_date": "1975-10-27",
  "anniversary": "1998-11-29",
  "client_since": "2002-05-21",
  "date_of_death": "2018-01-21",
  "assigned_to": 1,
  "referred_by": 1,
  "type": "Person",
  "gender": "Female",
  "contact_source": "Referral",
  "contact_type": "Client",
  "status": "Active",
  "marital_status": "Married",
  "attorney": 1,
  "cpa": 1,
  "doctor": 1,
  "insurance": 1,
  "business_manager": 1,
  "family_officer": 1,
  "assistant": 1,
  "other": 1,
  "trusted_contact": 1,
  "important_information": "Has 3 kids in college",
  "personal_interests": "Skiing: Downhill, Traveling",
  "investment_objective": "Aggressive Growth",
  "time_horizon": "Short Term",
  "risk_tolerance": "Low",
  "mutual_fund_experience": 3,
  "stocks_and_bonds_experience": 2,
  "partnerships_experience": 1,
  "other_investing_experience": 5,
  "gross_annual_income": 100000,
  "assets": 250000,
  "non_liquid_assets": 50000,
  "liabilities": 50000,
  "adjusted_gross_income": 75000,
  "estimated_taxes": 18000,
  "confirmed_by_tax_return": true,
  "tax_year": 2015,
  "tax_bracket": 10,
  "birth_place": "New York, NY",
  "maiden_name": "Anderson",
  "passport_number": "AB1234CD5689",
  "green_card_number": "ZX567HG134",
  "occupation": {
    "name": "CEO",
    "start_date": "2015-11-25"
  },
  "drivers_license": {
    "number": "1111111",
    "state": "New York",
    "issued_date": "2001-10-27",
    "expires_date": "2011-10-27"
  },
  "retirement_date": "2025-09-30",
  "signed_fee_agreement_date": "2013-05-15",
  "signed_ips_agreement_date": "2014-03-12",
  "signed_fp_agreement_date": "2015-03-12",
  "last_adv_offering_date": "2013-09-21",
  "initial_crs_offering_date": "2012-09-21",
  "last_crs_offering_date": "2013-09-21",
  "last_privacy_offering_date": "2011-10-23",
  "household": {
    "name": "The Anderson's",
    "title": "Head",
    "id": 1,
    "members": [
      {
        "id": 1,
        "first_name": "Kevin",
        "last_name": "Anderson",
        "title": "Head",
        "type": "Person"
      }
    ]
  },
  "image": "https://app.crmworkspace.com/avatar.png",
  "tags": [
    {
      "id": 1,
      "name": "Clients"
    }
  ],
  "street_addresses": [
    {
      "street_line_1": "155 12th Ave.",
      "street_line_2": "Apt 3B",
      "city": "New York",
      "state": "New York",
      "zip_code": "10001",
      "country": "United States",
      "principal": true,
      "kind": "Work",
      "id": 1,
      "address": "155 12th Ave., Apt 3B, New York, New York 10001, United States"
    }
  ],
  "email_addresses": [
    {
      "id": 1,
      "address": "kevin.anderson@example.com",
      "principal": true,
      "kind": "Work"
    }
  ],
  "phone_numbers": [
    {
      "id": 1,
      "address": "(555) 555-5555",
      "principal": true,
      "extension": "77",
      "kind": "Work"
    }
  ],
  "websites": [
    {
      "id": 1,
      "address": "https://www.example.com",
      "principal": true,
      "kind": "Website"
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ],
  "contact_roles": [
    {
      "id": 1,
      "name": "Planning Advisor",
      "value": 1,
      "assigned_to": {
        "id": 1,
        "type": "User",
        "name": "Kevin Anderson"
      }
    }
  ]
}

Contact¶

GET
Fetch an existing contact
`/v1/contacts/{id}`

Retrieve a specific contact using it unique identifier. The contact returned will include the attributes listed below.

Parameters

id number, required: The id of the contact to be updated

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
prefix string: The preferred prefix for the Contact
first_name string, required: The first name of the Contact
middle_name string: The middle name of the Contact
last_name string, required: The last name of the Contact
suffix string: The suffix associated with the Contact
nickname string: A preferred shortname for the Contact
job_title string: The title the contact holds at his/her present company
company_name string: The name of the contact’s present company
twitter_name string: The twitter handle of the contact
linkedin_url string: The LinkedIn url for the contact
background_information string: A brief description of the contact in a longer format
birth_date Date: The birthdate of the contact
anniversary Date: The wedding anniversary of the contact
client_since Date: The date when the contact became a client
date_of_death Date: The date of death of the contact
assigned_to number: The id of the User who is assigned to this contact
referred_by number: The id of the Contact who referred this Contact to the firm
type string: The type of the Contact being created

Choices: Person Household Organization Trust
gender string: The gender of the Contact

Choices: Female Male Non-binary Unknown
contact_source string: The method in which this contact was taken on as new business

Choices: Referral Conference Direct Mail Cold Call Other
contact_type string: A string further classifying the Contact

Choices: Client Past Client Prospect Vendor Organization
status string: A flag indicating whether or not the contact is currently active

Choices: Active Inactive
marital_status string: The marital status of the contact

Choices: Married Single Divorced Widowed Life Partner Separated Unknown
attorney number: The id of the Contact acting as this Contact’s attorney
cpa number: The id of the Contact acting as this Contact’s accountant
doctor number: The id of the Contact acting as this Contact’s doctor
insurance number: The id of the Contact acting as this Contact’s insurance agent
business_manager number: The id of the Contact acting as this Contact’s business manager
family_officer number: The id of the Contact acting as this Contact’s family officer
assistant number: The id of the Contact acting as this Contact’s assistant
other number: The id of the Contact acting as this Contact’s other
trusted_contact number: The id of the Contact acting as this Contact’s trusted contact
important_information string: A block of text containing any other important info for the Contact
personal_interests string: A block of text containing personal interests for the Contact
investment_objective string: A basic classification of the Contact’s investment objectives

Choices: Aggressive Growth Growth Income Safety of Principal
time_horizon string: A basic classification of the time horizon for the Contact’s investment goals

Choices: Short Term Intermediate Long Term
risk_tolerance string: A basic classification of the Contact’s risk tolerance

Choices: Low Moderate High Risk
mutual_fund_experience number: Years of experience the contact has in the mutual fund market
stocks_and_bonds_experience number: Years of experience the contact has in the stocks and bonds fund market
partnerships_experience number: Years of experience the contact has in partnerships
other_investing_experience number: Years of experience the contact has in other aspects of the investment world
gross_annual_income number: The Contact’s estimated gross annual income
assets number: The value of all of the Contact’s holdings
non_liquid_assets number: The value of all of the Contact’s holdings that are illiquid
liabilities number: The total value of the Contact’s liabilities
adjusted_gross_income number: The Contact’s annual income adjusted for tax withholdings
estimated_taxes number: The total amount of taxes paid by the Contact during a tax year
confirmed_by_tax_return boolean: Flag to indicate if the Contact’s adjusted gross income and estimated taxes have been confirmed by their tax return
tax_year number: The year of the tax return that was used to confirm the Contact’s income and tax liability
tax_bracket number: Tax bracket that the Contact sits in according to his last recorded tax return
birth_place string: The city/state where the Contact was born
maiden_name string: The maiden name of the Contact is she has one
passport_number string: The passport number of the Contact
green_card_number string: The green card number of the Contact
occupation Occupation: An object representing critical information about the contact’s occupation
drivers_license DriversLicense: An object representing the contact’s driver’s license
retirement_date Date: The date when the Contact hope to retire
signed_fee_agreement_date Date: The date when the Contact’s fee agreement was signed
signed_ips_agreement_date Date: The date when the Contact’s IPS agreement was signed
signed_fp_agreement_date Date: The date when the Contact’s FP agreement was signed
last_adv_offering_date Date: The date when the Contact’s was last offered ADV
initial_crs_offering_date Date: The date when the Contact’s was initially offered CRS
last_crs_offering_date Date: The date when the Contact’s was last offered CRS
last_privacy_offering_date Date: The date when the Contact last signed their privacy agreement
company_name string: The name of the company the person is employed with
household Household: An object representing the contact’s household
image string: A expiring URL that links to the headshot for the contact valid for 7 days
tags Array (Tag): An array of tags that are associated with the contact
street_addresses Array (MailingAddress): An array of the street addresses associated with the contact
email_addresses Array (EmailAddress): An array of the email addresses associated with the contact
phone_numbers Array (PhoneNumber): An array of the phone numbers associated with the contact
websites Array (Website): An array of the websites associated with the contact
custom_fields Array (CustomField): An array of custom fields for this object
contact_roles Array (ContactRoleValue): An array of contact roles for this contact, with their assigned options

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "prefix": "Mr.",
  "first_name": "Kevin",
  "middle_name": "James",
  "last_name": "Anderson",
  "suffix": "M.D.",
  "nickname": "Kev",
  "job_title": "CEO",
  "company_name": "Acme Co.",
  "twitter_name": "kev.anderson",
  "linkedin_url": "linkedin.com/in/kanderson",
  "background_information": "Met Kevin at a conference.",
  "birth_date": "1975-10-27",
  "anniversary": "1998-11-29",
  "client_since": "2002-05-21",
  "date_of_death": "2018-01-21",
  "assigned_to": 1,
  "referred_by": 1,
  "type": "Person",
  "gender": "Female",
  "contact_source": "Referral",
  "contact_type": "Client",
  "status": "Active",
  "marital_status": "Married",
  "attorney": 1,
  "cpa": 1,
  "doctor": 1,
  "insurance": 1,
  "business_manager": 1,
  "family_officer": 1,
  "assistant": 1,
  "other": 1,
  "trusted_contact": 1,
  "important_information": "Has 3 kids in college",
  "personal_interests": "Skiing: Downhill, Traveling",
  "investment_objective": "Aggressive Growth",
  "time_horizon": "Short Term",
  "risk_tolerance": "Low",
  "mutual_fund_experience": 3,
  "stocks_and_bonds_experience": 2,
  "partnerships_experience": 1,
  "other_investing_experience": 5,
  "gross_annual_income": 100000,
  "assets": 250000,
  "non_liquid_assets": 50000,
  "liabilities": 50000,
  "adjusted_gross_income": 75000,
  "estimated_taxes": 18000,
  "confirmed_by_tax_return": true,
  "tax_year": 2015,
  "tax_bracket": 10,
  "birth_place": "New York, NY",
  "maiden_name": "Anderson",
  "passport_number": "AB1234CD5689",
  "green_card_number": "ZX567HG134",
  "occupation": {
    "name": "CEO",
    "start_date": "2015-11-25"
  },
  "drivers_license": {
    "number": "1111111",
    "state": "New York",
    "issued_date": "2001-10-27",
    "expires_date": "2011-10-27"
  },
  "retirement_date": "2025-09-30",
  "signed_fee_agreement_date": "2013-05-15",
  "signed_ips_agreement_date": "2014-03-12",
  "signed_fp_agreement_date": "2015-03-12",
  "last_adv_offering_date": "2013-09-21",
  "initial_crs_offering_date": "2012-09-21",
  "last_crs_offering_date": "2013-09-21",
  "last_privacy_offering_date": "2011-10-23",
  "household": {
    "name": "The Anderson's",
    "title": "Head",
    "id": 1,
    "members": [
      {
        "id": 1,
        "first_name": "Kevin",
        "last_name": "Anderson",
        "title": "Head",
        "type": "Person"
      }
    ]
  },
  "image": "https://app.crmworkspace.com/avatar.png",
  "tags": [
    {
      "id": 1,
      "name": "Clients"
    }
  ],
  "street_addresses": [
    {
      "street_line_1": "155 12th Ave.",
      "street_line_2": "Apt 3B",
      "city": "New York",
      "state": "New York",
      "zip_code": "10001",
      "country": "United States",
      "principal": true,
      "kind": "Work",
      "id": 1,
      "address": "155 12th Ave., Apt 3B, New York, New York 10001, United States"
    }
  ],
  "email_addresses": [
    {
      "id": 1,
      "address": "kevin.anderson@example.com",
      "principal": true,
      "kind": "Work"
    }
  ],
  "phone_numbers": [
    {
      "id": 1,
      "address": "(555) 555-5555",
      "principal": true,
      "extension": "77",
      "kind": "Work"
    }
  ],
  "websites": [
    {
      "id": 1,
      "address": "https://www.example.com",
      "principal": true,
      "kind": "Website"
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ],
  "contact_roles": [
    {
      "id": 1,
      "name": "Planning Advisor",
      "value": 1,
      "assigned_to": {
        "id": 1,
        "type": "User",
        "name": "Kevin Anderson"
      }
    }
  ]
}

PUT
Update an existing contact
`/v1/contacts/{id}`

Update a specific contact using it unique identifier. Any of the attributes that are returned by GET /v1/contacts/{id} may be updated using this request. All fields are optional; any fields not included in the request will not be updated. The contact returned will include all of the attributes for GET /v1/contacts/{id}, with the updated values of the attributes in the request.

Parameters

id number, required: The id of the contact to be updated

Request Attributes

nickname string: A preferred shortname for the Contact
company_name string: Updating this field will create a new Organization contact with the given name if one does not exist, or it will link an existing one to the contact.
contact_roles Array (ContactRoleValueRequest): Store the contact role and a selected option

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
prefix string: The preferred prefix for the Contact
first_name string, required: The first name of the Contact
middle_name string: The middle name of the Contact
last_name string, required: The last name of the Contact
suffix string: The suffix associated with the Contact
nickname string: A preferred shortname for the Contact
job_title string: The title the contact holds at his/her present company
company_name string: The name of the contact’s present company
twitter_name string: The twitter handle of the contact
linkedin_url string: The LinkedIn url for the contact
background_information string: A brief description of the contact in a longer format
birth_date Date: The birthdate of the contact
anniversary Date: The wedding anniversary of the contact
client_since Date: The date when the contact became a client
date_of_death Date: The date of death of the contact
assigned_to number: The id of the User who is assigned to this contact
referred_by number: The id of the Contact who referred this Contact to the firm
type string: The type of the Contact being created

Choices: Person Household Organization Trust
gender string: The gender of the Contact

Choices: Female Male Non-binary Unknown
contact_source string: The method in which this contact was taken on as new business

Choices: Referral Conference Direct Mail Cold Call Other
contact_type string: A string further classifying the Contact

Choices: Client Past Client Prospect Vendor Organization
status string: A flag indicating whether or not the contact is currently active

Choices: Active Inactive
marital_status string: The marital status of the contact

Choices: Married Single Divorced Widowed Life Partner Separated Unknown
attorney number: The id of the Contact acting as this Contact’s attorney
cpa number: The id of the Contact acting as this Contact’s accountant
doctor number: The id of the Contact acting as this Contact’s doctor
insurance number: The id of the Contact acting as this Contact’s insurance agent
business_manager number: The id of the Contact acting as this Contact’s business manager
family_officer number: The id of the Contact acting as this Contact’s family officer
assistant number: The id of the Contact acting as this Contact’s assistant
other number: The id of the Contact acting as this Contact’s other
trusted_contact number: The id of the Contact acting as this Contact’s trusted contact
important_information string: A block of text containing any other important info for the Contact
personal_interests string: A block of text containing personal interests for the Contact
investment_objective string: A basic classification of the Contact’s investment objectives

Choices: Aggressive Growth Growth Income Safety of Principal
time_horizon string: A basic classification of the time horizon for the Contact’s investment goals

Choices: Short Term Intermediate Long Term
risk_tolerance string: A basic classification of the Contact’s risk tolerance

Choices: Low Moderate High Risk
mutual_fund_experience number: Years of experience the contact has in the mutual fund market
stocks_and_bonds_experience number: Years of experience the contact has in the stocks and bonds fund market
partnerships_experience number: Years of experience the contact has in partnerships
other_investing_experience number: Years of experience the contact has in other aspects of the investment world
gross_annual_income number: The Contact’s estimated gross annual income
assets number: The value of all of the Contact’s holdings
non_liquid_assets number: The value of all of the Contact’s holdings that are illiquid
liabilities number: The total value of the Contact’s liabilities
adjusted_gross_income number: The Contact’s annual income adjusted for tax withholdings
estimated_taxes number: The total amount of taxes paid by the Contact during a tax year
confirmed_by_tax_return boolean: Flag to indicate if the Contact’s adjusted gross income and estimated taxes have been confirmed by their tax return
tax_year number: The year of the tax return that was used to confirm the Contact’s income and tax liability
tax_bracket number: Tax bracket that the Contact sits in according to his last recorded tax return
birth_place string: The city/state where the Contact was born
maiden_name string: The maiden name of the Contact is she has one
passport_number string: The passport number of the Contact
green_card_number string: The green card number of the Contact
occupation Occupation: An object representing critical information about the contact’s occupation
drivers_license DriversLicense: An object representing the contact’s driver’s license
retirement_date Date: The date when the Contact hope to retire
signed_fee_agreement_date Date: The date when the Contact’s fee agreement was signed
signed_ips_agreement_date Date: The date when the Contact’s IPS agreement was signed
signed_fp_agreement_date Date: The date when the Contact’s FP agreement was signed
last_adv_offering_date Date: The date when the Contact’s was last offered ADV
initial_crs_offering_date Date: The date when the Contact’s was initially offered CRS
last_crs_offering_date Date: The date when the Contact’s was last offered CRS
last_privacy_offering_date Date: The date when the Contact last signed their privacy agreement
company_name string: The name of the company the person is employed with
household Household: An object representing the contact’s household
image string: A expiring URL that links to the headshot for the contact valid for 7 days
tags Array (Tag): An array of tags that are associated with the contact
street_addresses Array (MailingAddress): An array of the street addresses associated with the contact
email_addresses Array (EmailAddress): An array of the email addresses associated with the contact
phone_numbers Array (PhoneNumber): An array of the phone numbers associated with the contact
websites Array (Website): An array of the websites associated with the contact
custom_fields Array (CustomField): An array of custom fields for this object
contact_roles Array (ContactRoleValue): An array of contact roles for this contact, with their assigned options

Request

Body

{
  "nickname": "Kev",
  "company_name": "Acme Co.",
  "contact_roles": [
    {
      "id": 1,
      "value": 1
    }
  ]
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "prefix": "Mr.",
  "first_name": "Kevin",
  "middle_name": "James",
  "last_name": "Anderson",
  "suffix": "M.D.",
  "nickname": "Kev",
  "job_title": "CEO",
  "company_name": "Acme Co.",
  "twitter_name": "kev.anderson",
  "linkedin_url": "linkedin.com/in/kanderson",
  "background_information": "Met Kevin at a conference.",
  "birth_date": "1975-10-27",
  "anniversary": "1998-11-29",
  "client_since": "2002-05-21",
  "date_of_death": "2018-01-21",
  "assigned_to": 1,
  "referred_by": 1,
  "type": "Person",
  "gender": "Female",
  "contact_source": "Referral",
  "contact_type": "Client",
  "status": "Active",
  "marital_status": "Married",
  "attorney": 1,
  "cpa": 1,
  "doctor": 1,
  "insurance": 1,
  "business_manager": 1,
  "family_officer": 1,
  "assistant": 1,
  "other": 1,
  "trusted_contact": 1,
  "important_information": "Has 3 kids in college",
  "personal_interests": "Skiing: Downhill, Traveling",
  "investment_objective": "Aggressive Growth",
  "time_horizon": "Short Term",
  "risk_tolerance": "Low",
  "mutual_fund_experience": 3,
  "stocks_and_bonds_experience": 2,
  "partnerships_experience": 1,
  "other_investing_experience": 5,
  "gross_annual_income": 100000,
  "assets": 250000,
  "non_liquid_assets": 50000,
  "liabilities": 50000,
  "adjusted_gross_income": 75000,
  "estimated_taxes": 18000,
  "confirmed_by_tax_return": true,
  "tax_year": 2015,
  "tax_bracket": 10,
  "birth_place": "New York, NY",
  "maiden_name": "Anderson",
  "passport_number": "AB1234CD5689",
  "green_card_number": "ZX567HG134",
  "occupation": {
    "name": "CEO",
    "start_date": "2015-11-25"
  },
  "drivers_license": {
    "number": "1111111",
    "state": "New York",
    "issued_date": "2001-10-27",
    "expires_date": "2011-10-27"
  },
  "retirement_date": "2025-09-30",
  "signed_fee_agreement_date": "2013-05-15",
  "signed_ips_agreement_date": "2014-03-12",
  "signed_fp_agreement_date": "2015-03-12",
  "last_adv_offering_date": "2013-09-21",
  "initial_crs_offering_date": "2012-09-21",
  "last_crs_offering_date": "2013-09-21",
  "last_privacy_offering_date": "2011-10-23",
  "household": {
    "name": "The Anderson's",
    "title": "Head",
    "id": 1,
    "members": [
      {
        "id": 1,
        "first_name": "Kevin",
        "last_name": "Anderson",
        "title": "Head",
        "type": "Person"
      }
    ]
  },
  "image": "https://app.crmworkspace.com/avatar.png",
  "tags": [
    {
      "id": 1,
      "name": "Clients"
    }
  ],
  "street_addresses": [
    {
      "street_line_1": "155 12th Ave.",
      "street_line_2": "Apt 3B",
      "city": "New York",
      "state": "New York",
      "zip_code": "10001",
      "country": "United States",
      "principal": true,
      "kind": "Work",
      "id": 1,
      "address": "155 12th Ave., Apt 3B, New York, New York 10001, United States"
    }
  ],
  "email_addresses": [
    {
      "id": 1,
      "address": "kevin.anderson@example.com",
      "principal": true,
      "kind": "Work"
    }
  ],
  "phone_numbers": [
    {
      "id": 1,
      "address": "(555) 555-5555",
      "principal": true,
      "extension": "77",
      "kind": "Work"
    }
  ],
  "websites": [
    {
      "id": 1,
      "address": "https://www.example.com",
      "principal": true,
      "kind": "Website"
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ],
  "contact_roles": [
    {
      "id": 1,
      "name": "Planning Advisor",
      "value": 1,
      "assigned_to": {
        "id": 1,
        "type": "User",
        "name": "Kevin Anderson"
      }
    }
  ]
}

DELETE
Delete an existing contact
`/v1/contacts/{id}`

Delete a specific contact using it unique identifier.

Parameters

id number, required: The id of the contact to be updated

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
prefix string: The preferred prefix for the Contact
first_name string, required: The first name of the Contact
middle_name string: The middle name of the Contact
last_name string, required: The last name of the Contact
suffix string: The suffix associated with the Contact
nickname string: A preferred shortname for the Contact
job_title string: The title the contact holds at his/her present company
company_name string: The name of the contact’s present company
twitter_name string: The twitter handle of the contact
linkedin_url string: The LinkedIn url for the contact
background_information string: A brief description of the contact in a longer format
birth_date Date: The birthdate of the contact
anniversary Date: The wedding anniversary of the contact
client_since Date: The date when the contact became a client
date_of_death Date: The date of death of the contact
assigned_to number: The id of the User who is assigned to this contact
referred_by number: The id of the Contact who referred this Contact to the firm
type string: The type of the Contact being created

Choices: Person Household Organization Trust
gender string: The gender of the Contact

Choices: Female Male Non-binary Unknown
contact_source string: The method in which this contact was taken on as new business

Choices: Referral Conference Direct Mail Cold Call Other
contact_type string: A string further classifying the Contact

Choices: Client Past Client Prospect Vendor Organization
status string: A flag indicating whether or not the contact is currently active

Choices: Active Inactive
marital_status string: The marital status of the contact

Choices: Married Single Divorced Widowed Life Partner Separated Unknown
attorney number: The id of the Contact acting as this Contact’s attorney
cpa number: The id of the Contact acting as this Contact’s accountant
doctor number: The id of the Contact acting as this Contact’s doctor
insurance number: The id of the Contact acting as this Contact’s insurance agent
business_manager number: The id of the Contact acting as this Contact’s business manager
family_officer number: The id of the Contact acting as this Contact’s family officer
assistant number: The id of the Contact acting as this Contact’s assistant
other number: The id of the Contact acting as this Contact’s other
trusted_contact number: The id of the Contact acting as this Contact’s trusted contact
important_information string: A block of text containing any other important info for the Contact
personal_interests string: A block of text containing personal interests for the Contact
investment_objective string: A basic classification of the Contact’s investment objectives

Choices: Aggressive Growth Growth Income Safety of Principal
time_horizon string: A basic classification of the time horizon for the Contact’s investment goals

Choices: Short Term Intermediate Long Term
risk_tolerance string: A basic classification of the Contact’s risk tolerance

Choices: Low Moderate High Risk
mutual_fund_experience number: Years of experience the contact has in the mutual fund market
stocks_and_bonds_experience number: Years of experience the contact has in the stocks and bonds fund market
partnerships_experience number: Years of experience the contact has in partnerships
other_investing_experience number: Years of experience the contact has in other aspects of the investment world
gross_annual_income number: The Contact’s estimated gross annual income
assets number: The value of all of the Contact’s holdings
non_liquid_assets number: The value of all of the Contact’s holdings that are illiquid
liabilities number: The total value of the Contact’s liabilities
adjusted_gross_income number: The Contact’s annual income adjusted for tax withholdings
estimated_taxes number: The total amount of taxes paid by the Contact during a tax year
confirmed_by_tax_return boolean: Flag to indicate if the Contact’s adjusted gross income and estimated taxes have been confirmed by their tax return
tax_year number: The year of the tax return that was used to confirm the Contact’s income and tax liability
tax_bracket number: Tax bracket that the Contact sits in according to his last recorded tax return
birth_place string: The city/state where the Contact was born
maiden_name string: The maiden name of the Contact is she has one
passport_number string: The passport number of the Contact
green_card_number string: The green card number of the Contact
occupation Occupation: An object representing critical information about the contact’s occupation
drivers_license DriversLicense: An object representing the contact’s driver’s license
retirement_date Date: The date when the Contact hope to retire
signed_fee_agreement_date Date: The date when the Contact’s fee agreement was signed
signed_ips_agreement_date Date: The date when the Contact’s IPS agreement was signed
signed_fp_agreement_date Date: The date when the Contact’s FP agreement was signed
last_adv_offering_date Date: The date when the Contact’s was last offered ADV
initial_crs_offering_date Date: The date when the Contact’s was initially offered CRS
last_crs_offering_date Date: The date when the Contact’s was last offered CRS
last_privacy_offering_date Date: The date when the Contact last signed their privacy agreement
company_name string: The name of the company the person is employed with
household Household: An object representing the contact’s household
image string: A expiring URL that links to the headshot for the contact valid for 7 days
tags Array (Tag): An array of tags that are associated with the contact
street_addresses Array (MailingAddress): An array of the street addresses associated with the contact
email_addresses Array (EmailAddress): An array of the email addresses associated with the contact
phone_numbers Array (PhoneNumber): An array of the phone numbers associated with the contact
websites Array (Website): An array of the websites associated with the contact
custom_fields Array (CustomField): An array of custom fields for this object
contact_roles Array (ContactRoleValue): An array of contact roles for this contact, with their assigned options
birth_date Date: The birthdate of the contact
anniversary Date: The wedding anniversary of the contact
client_since Date: The date when the contact became a client
date_of_death Date: The date of the contact’s passing

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "prefix": "Mr.",
  "first_name": "Kevin",
  "middle_name": "James",
  "last_name": "Anderson",
  "suffix": "M.D.",
  "nickname": "Kev",
  "job_title": "CEO",
  "company_name": "Acme Co.",
  "twitter_name": "kev.anderson",
  "linkedin_url": "linkedin.com/in/kanderson",
  "background_information": "Met Kevin at a conference.",
  "birth_date": "1975-10-27",
  "anniversary": "1998-11-29",
  "client_since": "2002-05-21",
  "date_of_death": "2018-01-21",
  "assigned_to": 1,
  "referred_by": 1,
  "type": "Person",
  "gender": "Female",
  "contact_source": "Referral",
  "contact_type": "Client",
  "status": "Active",
  "marital_status": "Married",
  "attorney": 1,
  "cpa": 1,
  "doctor": 1,
  "insurance": 1,
  "business_manager": 1,
  "family_officer": 1,
  "assistant": 1,
  "other": 1,
  "trusted_contact": 1,
  "important_information": "Has 3 kids in college",
  "personal_interests": "Skiing: Downhill, Traveling",
  "investment_objective": "Aggressive Growth",
  "time_horizon": "Short Term",
  "risk_tolerance": "Low",
  "mutual_fund_experience": 3,
  "stocks_and_bonds_experience": 2,
  "partnerships_experience": 1,
  "other_investing_experience": 5,
  "gross_annual_income": 100000,
  "assets": 250000,
  "non_liquid_assets": 50000,
  "liabilities": 50000,
  "adjusted_gross_income": 75000,
  "estimated_taxes": 18000,
  "confirmed_by_tax_return": true,
  "tax_year": 2015,
  "tax_bracket": 10,
  "birth_place": "New York, NY",
  "maiden_name": "Anderson",
  "passport_number": "AB1234CD5689",
  "green_card_number": "ZX567HG134",
  "occupation": {
    "name": "CEO",
    "start_date": "2015-11-25"
  },
  "drivers_license": {
    "number": "1111111",
    "state": "New York",
    "issued_date": "2001-10-27",
    "expires_date": "2011-10-27"
  },
  "retirement_date": "2025-09-30",
  "signed_fee_agreement_date": "2013-05-15",
  "signed_ips_agreement_date": "2014-03-12",
  "signed_fp_agreement_date": "2015-03-12",
  "last_adv_offering_date": "2013-09-21",
  "initial_crs_offering_date": "2012-09-21",
  "last_crs_offering_date": "2013-09-21",
  "last_privacy_offering_date": "2011-10-23",
  "household": {
    "name": "The Anderson's",
    "title": "Head",
    "id": 1,
    "members": [
      {
        "id": 1,
        "first_name": "Kevin",
        "last_name": "Anderson",
        "title": "Head",
        "type": "Person"
      }
    ]
  },
  "image": "https://app.crmworkspace.com/avatar.png",
  "tags": [
    {
      "id": 1,
      "name": "Clients"
    }
  ],
  "street_addresses": [
    {
      "street_line_1": "155 12th Ave.",
      "street_line_2": "Apt 3B",
      "city": "New York",
      "state": "New York",
      "zip_code": "10001",
      "country": "United States",
      "principal": true,
      "kind": "Work",
      "id": 1,
      "address": "155 12th Ave., Apt 3B, New York, New York 10001, United States"
    }
  ],
  "email_addresses": [
    {
      "id": 1,
      "address": "kevin.anderson@example.com",
      "principal": true,
      "kind": "Work"
    }
  ],
  "phone_numbers": [
    {
      "id": 1,
      "address": "(555) 555-5555",
      "principal": true,
      "extension": "77",
      "kind": "Work"
    }
  ],
  "websites": [
    {
      "id": 1,
      "address": "https://www.example.com",
      "principal": true,
      "kind": "Website"
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ],
  "contact_roles": [
    {
      "id": 1,
      "name": "Planning Advisor",
      "value": 1,
      "assigned_to": {
        "id": 1,
        "type": "User",
        "name": "Kevin Anderson"
      }
    }
  ]
}

Collection¶

GET
Retrieve all tasks
`/v1/tasks{?resource_id}{?resource_type}{?assigned_to}{?assigned_to_team}{?created_by}{?completed}`

This endpoint will fetch all of the tasks that are accessible by the user. This way the user can not access any tasks they don’t have access to.

Parameters

resource_id number: The id of the resource being searched for
resource_type string: The type of resource being searched for
assigned_to number: The id of the User which the task is assigned to
assigned_to_team number: The id of the Team which the task is assigned to
created_by number: The id of the User who created the task
completed boolean: Return completed tasks as well

Response Attributes

tasks Array (undefined)

Response 200

Body

{
  "tasks": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "name": "Return Bill's call",
      "due_date": "2015-05-24 11:00 AM -0400",
      "complete": true,
      "category": 1,
      "linked_to": [
        {
          "id": 1,
          "type": "Contact",
          "name": "Kevin Anderson"
        }
      ],
      "priority": "Low",
      "visible_to": "Everyone",
      "custom_fields": [
        {
          "id": 1,
          "name": "My Field",
          "value": "123456789",
          "document_type": "Contact",
          "field_type": "single_select"
        }
      ],
      "frame": "today",
      "repeats": true,
      "completer": 1,
      "description": "Follow up from message...",
      "description_html": "<div>Follow up from message...</div>",
      "assigned_to": 1
    },
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "name": "Return Bill's call",
      "due_date": "2015-05-24 11:00 AM -0400",
      "complete": true,
      "category": 1,
      "linked_to": [
        {
          "id": 1,
          "type": "Contact",
          "name": "Kevin Anderson"
        }
      ],
      "priority": "Low",
      "visible_to": "Everyone",
      "custom_fields": [
        {
          "id": 1,
          "name": "My Field",
          "value": "123456789",
          "document_type": "Contact",
          "field_type": "single_select"
        }
      ],
      "frame": "today",
      "repeats": true,
      "completer": 1,
      "description": "Follow up from message...",
      "description_html": "<div>Follow up from message...</div>",
      "assigned_to_team": 10
    }
  ]
}

POST
Create a new task and assign it to a user
`/v1/tasks`

Create a new task and assign it to a user.

Request Attributes

name string, required: The name of the task being returned
due_date Datetime, required: The time at which the task is due
complete boolean: Flag to indicate whether or not the task is complete
category number: The category the task will belong to
linked_to Array (Document): An array of resources that are linked to this task. Supported resource types: Contacts, projects, and opportunities.
priority string: String to indicate the priority of the task you are creating

Choices: Low Medium High
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomFieldRequest): An array of custom fields for this object
assigned_to number: The id of the user who the task is assigned to
description string: A short explaination of the task being returned as plain text or html

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the task being returned
due_date Datetime, required: The time at which the task is due
complete boolean: Flag to indicate whether or not the task is complete
category number: The category the task will belong to
linked_to Array (Document): An array of resources that are linked to this task. Supported resource types: Contacts, projects, and opportunities.
priority string: String to indicate the priority of the task you are creating

Choices: Low Medium High
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomField): An array of custom fields for this object
frame string: String to indicate the task’s frame
repeats boolean: Flag to indicate whether or not the task repeats
completer number: The id of the user who completed the task
description string: A short explaination of the task being returned as plain text
description_html string: A short explaination of the task being returned as html
assigned_to number: The id of the user who the task is assigned to

Request

Body

{
  "name": "Return Bill's call",
  "due_date": "2015-05-24 11:00 AM -0400",
  "complete": true,
  "category": 1,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "priority": "Low",
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "value": "123456789"
    }
  ],
  "assigned_to": 1,
  "description": "Follow up from message..."
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Return Bill's call",
  "due_date": "2015-05-24 11:00 AM -0400",
  "complete": true,
  "category": 1,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "priority": "Low",
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ],
  "frame": "today",
  "repeats": true,
  "completer": 1,
  "description": "Follow up from message...",
  "description_html": "<div>Follow up from message...</div>",
  "assigned_to": 1
}

POST
Create a new task and assign it to a team
`/v1/tasks`

Create a new task and assign it to a team.

Request Attributes

name string, required: The name of the task being returned
due_date Datetime, required: The time at which the task is due
complete boolean: Flag to indicate whether or not the task is complete
category number: The category the task will belong to
linked_to Array (Document): An array of resources that are linked to this task. Supported resource types: Contacts, projects, and opportunities.
priority string: String to indicate the priority of the task you are creating

Choices: Low Medium High
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomFieldRequest): An array of custom fields for this object
assigned_to_team number: The id of the team which the task is assigned to
description string: A short explaination of the task being returned as plain text or html

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the task being returned
due_date Datetime, required: The time at which the task is due
complete boolean: Flag to indicate whether or not the task is complete
category number: The category the task will belong to
linked_to Array (Document): An array of resources that are linked to this task. Supported resource types: Contacts, projects, and opportunities.
priority string: String to indicate the priority of the task you are creating

Choices: Low Medium High
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomField): An array of custom fields for this object
frame string: String to indicate the task’s frame
repeats boolean: Flag to indicate whether or not the task repeats
completer number: The id of the user who completed the task
description string: A short explaination of the task being returned as plain text
description_html string: A short explaination of the task being returned as html
assigned_to_team number: The id of the team which the task is assigned to

Request

Body

{
  "name": "Return Bill's call",
  "due_date": "2015-05-24 11:00 AM -0400",
  "complete": true,
  "category": 1,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "priority": "Low",
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "value": "123456789"
    }
  ],
  "assigned_to_team": 10,
  "description": "Follow up from message..."
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Return Bill's call",
  "due_date": "2015-05-24 11:00 AM -0400",
  "complete": true,
  "category": 1,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "priority": "Low",
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ],
  "frame": "today",
  "repeats": true,
  "completer": 1,
  "description": "Follow up from message...",
  "description_html": "<div>Follow up from message...</div>",
  "assigned_to_team": 10
}

Task¶

GET
Fetch an existing task
`/v1/tasks/{id}`

Retrieve a specific task using its unique identifier. The task returned will include the attributes listed below.

Parameters

id number, required: The id of the task to be updated

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the task being returned
due_date Datetime, required: The time at which the task is due
complete boolean: Flag to indicate whether or not the task is complete
category number: The category the task will belong to
linked_to Array (Document): An array of resources that are linked to this task. Supported resource types: Contacts, projects, and opportunities.
priority string: String to indicate the priority of the task you are creating

Choices: Low Medium High
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomField): An array of custom fields for this object
frame string: String to indicate the task’s frame
repeats boolean: Flag to indicate whether or not the task repeats
completer number: The id of the user who completed the task
description string: A short explaination of the task being returned as plain text
description_html string: A short explaination of the task being returned as html
assigned_to number: The id of the user who the task is assigned to

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Return Bill's call",
  "due_date": "2015-05-24 11:00 AM -0400",
  "complete": true,
  "category": 1,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "priority": "Low",
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ],
  "frame": "today",
  "repeats": true,
  "completer": 1,
  "description": "Follow up from message...",
  "description_html": "<div>Follow up from message...</div>",
  "assigned_to": 1
}

PUT
Update an existing task and assign it to a user
`/v1/tasks/{id}`

Update an existing task and assign it to a user with some new properties, these properties will be saved to the database and the new task will be returned.

Parameters

id number, required: The id of the task to be updated

Request Attributes

name string, required: The name of the task being returned
due_date Datetime, required: The time at which the task is due
complete boolean: Flag to indicate whether or not the task is complete
category number: The category the task will belong to
linked_to Array (Document): An array of resources that are linked to this task. Supported resource types: Contacts, projects, and opportunities.
priority string: String to indicate the priority of the task you are creating

Choices: Low Medium High
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomFieldRequest): An array of custom fields for this object
assigned_to number: The id of the user who the task is assigned to
description string: A short explaination of the task being returned as plain text or html

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the task being returned
due_date Datetime, required: The time at which the task is due
complete boolean: Flag to indicate whether or not the task is complete
category number: The category the task will belong to
linked_to Array (Document): An array of resources that are linked to this task. Supported resource types: Contacts, projects, and opportunities.
priority string: String to indicate the priority of the task you are creating

Choices: Low Medium High
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomField): An array of custom fields for this object
frame string: String to indicate the task’s frame
repeats boolean: Flag to indicate whether or not the task repeats
completer number: The id of the user who completed the task
description string: A short explaination of the task being returned as plain text
description_html string: A short explaination of the task being returned as html
assigned_to number: The id of the user who the task is assigned to

Request

Body

{
  "name": "Return Bill's call",
  "due_date": "2015-05-24 11:00 AM -0400",
  "complete": true,
  "category": 1,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "priority": "Low",
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "value": "123456789"
    }
  ],
  "assigned_to": 1,
  "description": "Follow up from message..."
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Return Bill's call",
  "due_date": "2015-05-24 11:00 AM -0400",
  "complete": true,
  "category": 1,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "priority": "Low",
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ],
  "frame": "today",
  "repeats": true,
  "completer": 1,
  "description": "Follow up from message...",
  "description_html": "<div>Follow up from message...</div>",
  "assigned_to": 1
}

PUT
Update an existing task and assign it to a team
`/v1/tasks/{id}`

Update an existing task and assign it to a team with some new properties, these properties will be saved to the database and the new task will be returned.

Parameters

id number, required: The id of the task to be updated

Request Attributes

name string, required: The name of the task being returned
due_date Datetime, required: The time at which the task is due
complete boolean: Flag to indicate whether or not the task is complete
category number: The category the task will belong to
linked_to Array (Document): An array of resources that are linked to this task. Supported resource types: Contacts, projects, and opportunities.
priority string: String to indicate the priority of the task you are creating

Choices: Low Medium High
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomFieldRequest): An array of custom fields for this object
assigned_to_team number: The id of the team which the task is assigned to
description string: A short explaination of the task being returned as plain text or html

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the task being returned
due_date Datetime, required: The time at which the task is due
complete boolean: Flag to indicate whether or not the task is complete
category number: The category the task will belong to
linked_to Array (Document): An array of resources that are linked to this task. Supported resource types: Contacts, projects, and opportunities.
priority string: String to indicate the priority of the task you are creating

Choices: Low Medium High
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomField): An array of custom fields for this object
frame string: String to indicate the task’s frame
repeats boolean: Flag to indicate whether or not the task repeats
completer number: The id of the user who completed the task
description string: A short explaination of the task being returned as plain text
description_html string: A short explaination of the task being returned as html
assigned_to_team number: The id of the team which the task is assigned to

Request

Body

{
  "name": "Return Bill's call",
  "due_date": "2015-05-24 11:00 AM -0400",
  "complete": true,
  "category": 1,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "priority": "Low",
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "value": "123456789"
    }
  ],
  "assigned_to_team": 10,
  "description": "Follow up from message..."
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Return Bill's call",
  "due_date": "2015-05-24 11:00 AM -0400",
  "complete": true,
  "category": 1,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "priority": "Low",
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ],
  "frame": "today",
  "repeats": true,
  "completer": 1,
  "description": "Follow up from message...",
  "description_html": "<div>Follow up from message...</div>",
  "assigned_to_team": 10
}

DELETE
Delete task
`/v1/tasks/{id}`

Delete an existing task from your account (workspace). This task will not be available to you going forward in the future.

Parameters

id number, required: The id of the task to be updated

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the task being returned
due_date Datetime, required: The time at which the task is due
complete boolean: Flag to indicate whether or not the task is complete
category number: The category the task will belong to
linked_to Array (Document): An array of resources that are linked to this task. Supported resource types: Contacts, projects, and opportunities.
priority string: String to indicate the priority of the task you are creating

Choices: Low Medium High
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomField): An array of custom fields for this object
frame string: String to indicate the task’s frame
repeats boolean: Flag to indicate whether or not the task repeats
completer number: The id of the user who completed the task
description string: A short explaination of the task being returned as plain text
description_html string: A short explaination of the task being returned as html
assigned_to number: The id of the user who the task is assigned to

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Return Bill's call",
  "due_date": "2015-05-24 11:00 AM -0400",
  "complete": true,
  "category": 1,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "priority": "Low",
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ],
  "frame": "today",
  "repeats": true,
  "completer": 1,
  "description": "Follow up from message...",
  "description_html": "<div>Follow up from message...</div>",
  "assigned_to": 1
}

Collection¶

GET
Retrieve all workflows
`/v1/workflows{?resource_id}{?resource_type}{?status}`

This endpoint will fetch all of the workflows that are accessible by the user. This way the user can not access any workflows they don’t have access to.

Parameters

resource_id number: The id of the resource being searched for
resource_type string: The type of resource being searched for
status string: Only returns workflows whose status match the specified value

Choices: activecompletedscheduled

Response Attributes

workflows Array (Workflow)

Response 200

Body

{
  "workflows": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "label": "Onboard a new client to the firm",
      "linked_to": {
        "id": 1,
        "type": "Contact",
        "name": "Kevin Anderson"
      },
      "visible_to": "Everyone",
      "workflow_template": {
        "id": 1,
        "creator": 1,
        "created_at": "2015-05-24 10:00 AM -0400",
        "updated_at": "2015-10-12 11:30 PM -0400",
        "name": "New Client Onboarding Process",
        "sequential": true,
        "description": "Onboarding workflow for our clients...",
        "description_html": "<div>Onboarding workflow for our clients...</div>",
        "shared": true,
        "ready": true,
        "workflow_milestones": [
          {
            "id": "abcdef",
            "name": "Onboarding"
          }
        ],
        "workflow_steps": [
          {
            "id": 1,
            "creator": 1,
            "created_at": "2015-05-24 10:00 AM -0400",
            "updated_at": "2015-10-12 11:30 PM -0400",
            "name": "Schedule discover meeting",
            "description": "In this meeting, we will...",
            "description_html": "<div>In this meeting, we will...</div>",
            "workflow": 1,
            "assigned_to": 1,
            "due_based_on": "default",
            "due_date_set": true,
            "due_later": "2 days later at 5:00 PM",
            "due_date": "2024-03-06 11:30 AM -0500",
            "priority": "None",
            "workflow_outcomes": [
              {
                "id": 1,
                "workflow_step_id": 1,
                "name": "Meeting scheduled with client",
                "action": "Go to Step",
                "go_to_step_id": 2,
                "due_date_set": false,
                "due_later": "2 days later at 5:00 PM",
                "created_at": "2015-05-24 10:00 AM -0400",
                "updated_at": "2015-10-12 11:30 PM -0400"
              }
            ],
            "workflow_milestone_id": 1
          }
        ],
        "kind": "Contact",
        "visible_to": "Everyone"
      },
      "workflow_steps": [
        {
          "id": 1,
          "creator": 1,
          "created_at": "2015-05-24 10:00 AM -0400",
          "updated_at": "2015-10-12 11:30 PM -0400",
          "name": "Schedule discover meeting",
          "description": "In this meeting, we will...",
          "description_html": "<div>In this meeting, we will...</div>",
          "workflow": 1,
          "assigned_to": 1,
          "due_based_on": "default",
          "due_date_set": true,
          "due_later": "2 days later at 5:00 PM",
          "due_date": "2024-03-06 11:30 AM -0500",
          "priority": "None",
          "workflow_outcomes": [
            {
              "id": 1,
              "workflow_step_id": 1,
              "name": "Meeting scheduled with client",
              "action": "Go to Step",
              "go_to_step_id": 2,
              "due_date_set": false,
              "due_later": "2 days later at 5:00 PM",
              "created_at": "2015-05-24 10:00 AM -0400",
              "updated_at": "2015-10-12 11:30 PM -0400"
            }
          ],
          "workflow_milestone_id": 1
        }
      ],
      "workflow_milestones": [
        {
          "id": 1,
          "name": "Onboarding",
          "milestone_date": "2015-05-24 10:00 AM -0400"
        }
      ],
      "starts_at": "2019-02-25 03:00 PM -0400",
      "started_at": "2019-02-25 03:00 PM -0400"
    }
  ]
}

POST
Create a new workflow
`/v1/workflows`

Create a new Workflow.

Request Attributes

label string: A short name for the Workflow
linked_to Document: An object that is linked to this Workflow
visible_to string: The user group which is able to view the resource being created
workflow_template number, required: The id of the workflow template this workflow is based on
starts_at Datetime: The date (time is optional) you want the workflow to start
workflow_milestones Array (undefined): An array of all workflow milestones needed for the provided workflow template

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
label string: A short name for the Workflow
linked_to Document: An object that is linked to this Workflow
visible_to string: The user group which is able to view the resource being created
workflow_template WorkflowTemplate: The workflow template related to the specified workflow
workflow_steps Array (WorkflowStep): An array of all workflow steps related to this Workflow
workflow_milestones Array (WorkflowMilestone): An array of all workflow milestones related to this Workflow
starts_at Datetime: When the workflow is set to start
started_at Datetime: When the workflow was started

Request

Body

{
  "label": "Onboard a new client to the firm",
  "linked_to": {
    "id": 1,
    "type": "Contact",
    "name": "Kevin Anderson"
  },
  "visible_to": "Everyone",
  "workflow_template": 2,
  "starts_at": "2019-02-25 3:00pm",
  "workflow_milestones": [
    {
      "id": "abcdef",
      "name": "Onboarding",
      "milestone_date": "2015-05-24 10:00 AM -0400"
    },
    {
      "id": "ghijkl",
      "name": "Account Opening",
      "milestone_date": "2015-06-24 10:00 AM -0400"
    }
  ]
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "label": "Onboard a new client to the firm",
  "linked_to": {
    "id": 1,
    "type": "Contact",
    "name": "Kevin Anderson"
  },
  "visible_to": "Everyone",
  "workflow_template": {
    "id": 1,
    "creator": 1,
    "created_at": "2015-05-24 10:00 AM -0400",
    "updated_at": "2015-10-12 11:30 PM -0400",
    "name": "New Client Onboarding Process",
    "sequential": true,
    "description": "Onboarding workflow for our clients...",
    "description_html": "<div>Onboarding workflow for our clients...</div>",
    "shared": true,
    "ready": true,
    "workflow_milestones": [
      {
        "id": "abcdef",
        "name": "Onboarding"
      }
    ],
    "workflow_steps": [
      {
        "id": 1,
        "creator": 1,
        "created_at": "2015-05-24 10:00 AM -0400",
        "updated_at": "2015-10-12 11:30 PM -0400",
        "name": "Schedule discover meeting",
        "description": "In this meeting, we will...",
        "description_html": "<div>In this meeting, we will...</div>",
        "workflow": 1,
        "assigned_to": 1,
        "due_based_on": "default",
        "due_date_set": true,
        "due_later": "2 days later at 5:00 PM",
        "due_date": "2024-03-06 11:30 AM -0500",
        "priority": "None",
        "workflow_outcomes": [
          {
            "id": 1,
            "workflow_step_id": 1,
            "name": "Meeting scheduled with client",
            "action": "Go to Step",
            "go_to_step_id": 2,
            "due_date_set": false,
            "due_later": "2 days later at 5:00 PM",
            "created_at": "2015-05-24 10:00 AM -0400",
            "updated_at": "2015-10-12 11:30 PM -0400"
          }
        ],
        "workflow_milestone_id": 1
      }
    ],
    "kind": "Contact",
    "visible_to": "Everyone"
  },
  "workflow_steps": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "name": "Schedule discover meeting",
      "description": "In this meeting, we will...",
      "description_html": "<div>In this meeting, we will...</div>",
      "workflow": 1,
      "assigned_to": 1,
      "due_based_on": "default",
      "due_date_set": true,
      "due_later": "2 days later at 5:00 PM",
      "due_date": "2024-03-06 11:30 AM -0500",
      "priority": "None",
      "workflow_outcomes": [
        {
          "id": 1,
          "workflow_step_id": 1,
          "name": "Meeting scheduled with client",
          "action": "Go to Step",
          "go_to_step_id": 2,
          "due_date_set": false,
          "due_later": "2 days later at 5:00 PM",
          "created_at": "2015-05-24 10:00 AM -0400",
          "updated_at": "2015-10-12 11:30 PM -0400"
        }
      ],
      "workflow_milestone_id": 1
    }
  ],
  "workflow_milestones": [
    {
      "id": 1,
      "name": "Onboarding",
      "milestone_date": "2015-05-24 10:00 AM -0400"
    }
  ],
  "starts_at": "2019-02-25 03:00 PM -0400",
  "started_at": "2019-02-25 03:00 PM -0400"
}

Workflow¶

GET
Fetch an existing workflow
`/v1/workflows/{id}`

Retrieve a specific workflow using it unique identifier. The workflow returned will include the attributes listed below.

Parameters

id number, required: The id of the workflow to be updated

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
label string: A short name for the Workflow
linked_to Document: An object that is linked to this Workflow
visible_to string: The user group which is able to view the resource being created
workflow_template WorkflowTemplate: The workflow template related to the specified workflow
workflow_steps Array (WorkflowStep): An array of all workflow steps related to this Workflow
workflow_milestones Array (WorkflowMilestone): An array of all workflow milestones related to this Workflow
starts_at Datetime: When the workflow is set to start
started_at Datetime: When the workflow was started

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "label": "Onboard a new client to the firm",
  "linked_to": {
    "id": 1,
    "type": "Contact",
    "name": "Kevin Anderson"
  },
  "visible_to": "Everyone",
  "workflow_template": {
    "id": 1,
    "creator": 1,
    "created_at": "2015-05-24 10:00 AM -0400",
    "updated_at": "2015-10-12 11:30 PM -0400",
    "name": "New Client Onboarding Process",
    "sequential": true,
    "description": "Onboarding workflow for our clients...",
    "description_html": "<div>Onboarding workflow for our clients...</div>",
    "shared": true,
    "ready": true,
    "workflow_milestones": [
      {
        "id": "abcdef",
        "name": "Onboarding"
      }
    ],
    "workflow_steps": [
      {
        "id": 1,
        "creator": 1,
        "created_at": "2015-05-24 10:00 AM -0400",
        "updated_at": "2015-10-12 11:30 PM -0400",
        "name": "Schedule discover meeting",
        "description": "In this meeting, we will...",
        "description_html": "<div>In this meeting, we will...</div>",
        "workflow": 1,
        "assigned_to": 1,
        "due_based_on": "default",
        "due_date_set": true,
        "due_later": "2 days later at 5:00 PM",
        "due_date": "2024-03-06 11:30 AM -0500",
        "priority": "None",
        "workflow_outcomes": [
          {
            "id": 1,
            "workflow_step_id": 1,
            "name": "Meeting scheduled with client",
            "action": "Go to Step",
            "go_to_step_id": 2,
            "due_date_set": false,
            "due_later": "2 days later at 5:00 PM",
            "created_at": "2015-05-24 10:00 AM -0400",
            "updated_at": "2015-10-12 11:30 PM -0400"
          }
        ],
        "workflow_milestone_id": 1
      }
    ],
    "kind": "Contact",
    "visible_to": "Everyone"
  },
  "workflow_steps": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "name": "Schedule discover meeting",
      "description": "In this meeting, we will...",
      "description_html": "<div>In this meeting, we will...</div>",
      "workflow": 1,
      "assigned_to": 1,
      "due_based_on": "default",
      "due_date_set": true,
      "due_later": "2 days later at 5:00 PM",
      "due_date": "2024-03-06 11:30 AM -0500",
      "priority": "None",
      "workflow_outcomes": [
        {
          "id": 1,
          "workflow_step_id": 1,
          "name": "Meeting scheduled with client",
          "action": "Go to Step",
          "go_to_step_id": 2,
          "due_date_set": false,
          "due_later": "2 days later at 5:00 PM",
          "created_at": "2015-05-24 10:00 AM -0400",
          "updated_at": "2015-10-12 11:30 PM -0400"
        }
      ],
      "workflow_milestone_id": 1
    }
  ],
  "workflow_milestones": [
    {
      "id": 1,
      "name": "Onboarding",
      "milestone_date": "2015-05-24 10:00 AM -0400"
    }
  ],
  "starts_at": "2019-02-25 03:00 PM -0400",
  "started_at": "2019-02-25 03:00 PM -0400"
}

DELETE
Delete workflow
`/v1/workflows/{id}`

Delete an existing workflow from your account (workspace). This workflow will not be available to you going forward in the future.

Parameters

id number, required: The id of the workflow to be updated

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
label string: A short name for the Workflow
linked_to Document: An object that is linked to this Workflow
visible_to string: The user group which is able to view the resource being created
workflow_template WorkflowTemplate: The workflow template related to the specified workflow
workflow_steps Array (WorkflowStep): An array of all workflow steps related to this Workflow
workflow_milestones Array (WorkflowMilestone): An array of all workflow milestones related to this Workflow
starts_at Datetime: When the workflow is set to start
started_at Datetime: When the workflow was started

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "label": "Onboard a new client to the firm",
  "linked_to": {
    "id": 1,
    "type": "Contact",
    "name": "Kevin Anderson"
  },
  "visible_to": "Everyone",
  "workflow_template": {
    "id": 1,
    "creator": 1,
    "created_at": "2015-05-24 10:00 AM -0400",
    "updated_at": "2015-10-12 11:30 PM -0400",
    "name": "New Client Onboarding Process",
    "sequential": true,
    "description": "Onboarding workflow for our clients...",
    "description_html": "<div>Onboarding workflow for our clients...</div>",
    "shared": true,
    "ready": true,
    "workflow_milestones": [
      {
        "id": "abcdef",
        "name": "Onboarding"
      }
    ],
    "workflow_steps": [
      {
        "id": 1,
        "creator": 1,
        "created_at": "2015-05-24 10:00 AM -0400",
        "updated_at": "2015-10-12 11:30 PM -0400",
        "name": "Schedule discover meeting",
        "description": "In this meeting, we will...",
        "description_html": "<div>In this meeting, we will...</div>",
        "workflow": 1,
        "assigned_to": 1,
        "due_based_on": "default",
        "due_date_set": true,
        "due_later": "2 days later at 5:00 PM",
        "due_date": "2024-03-06 11:30 AM -0500",
        "priority": "None",
        "workflow_outcomes": [
          {
            "id": 1,
            "workflow_step_id": 1,
            "name": "Meeting scheduled with client",
            "action": "Go to Step",
            "go_to_step_id": 2,
            "due_date_set": false,
            "due_later": "2 days later at 5:00 PM",
            "created_at": "2015-05-24 10:00 AM -0400",
            "updated_at": "2015-10-12 11:30 PM -0400"
          }
        ],
        "workflow_milestone_id": 1
      }
    ],
    "kind": "Contact",
    "visible_to": "Everyone"
  },
  "workflow_steps": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "name": "Schedule discover meeting",
      "description": "In this meeting, we will...",
      "description_html": "<div>In this meeting, we will...</div>",
      "workflow": 1,
      "assigned_to": 1,
      "due_based_on": "default",
      "due_date_set": true,
      "due_later": "2 days later at 5:00 PM",
      "due_date": "2024-03-06 11:30 AM -0500",
      "priority": "None",
      "workflow_outcomes": [
        {
          "id": 1,
          "workflow_step_id": 1,
          "name": "Meeting scheduled with client",
          "action": "Go to Step",
          "go_to_step_id": 2,
          "due_date_set": false,
          "due_later": "2 days later at 5:00 PM",
          "created_at": "2015-05-24 10:00 AM -0400",
          "updated_at": "2015-10-12 11:30 PM -0400"
        }
      ],
      "workflow_milestone_id": 1
    }
  ],
  "workflow_milestones": [
    {
      "id": 1,
      "name": "Onboarding",
      "milestone_date": "2015-05-24 10:00 AM -0400"
    }
  ],
  "starts_at": "2019-02-25 03:00 PM -0400",
  "started_at": "2019-02-25 03:00 PM -0400"
}

Collection¶

GET
Retrieve all workflow templates
`/v1/workflow_templates`

This endpoint will fetch all of the workflow templates that are accessible by the user. This way the user can not access any workflow templates they don’t have access to.

Response Attributes

workflow_templates Array (WorkflowTemplate)

Response 200

Body

{
  "workflow_templates": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "name": "New Client Onboarding Process",
      "sequential": true,
      "description": "Onboarding workflow for our clients...",
      "description_html": "<div>Onboarding workflow for our clients...</div>",
      "shared": true,
      "ready": true,
      "workflow_milestones": [
        {
          "id": "abcdef",
          "name": "Onboarding"
        }
      ],
      "workflow_steps": [
        {
          "id": 1,
          "creator": 1,
          "created_at": "2015-05-24 10:00 AM -0400",
          "updated_at": "2015-10-12 11:30 PM -0400",
          "name": "Schedule discover meeting",
          "description": "In this meeting, we will...",
          "description_html": "<div>In this meeting, we will...</div>",
          "workflow": 1,
          "assigned_to": 1,
          "due_based_on": "default",
          "due_date_set": true,
          "due_later": "2 days later at 5:00 PM",
          "due_date": "2024-03-06 11:30 AM -0500",
          "priority": "None",
          "workflow_outcomes": [
            {
              "id": 1,
              "workflow_step_id": 1,
              "name": "Meeting scheduled with client",
              "action": "Go to Step",
              "go_to_step_id": 2,
              "due_date_set": false,
              "due_later": "2 days later at 5:00 PM",
              "created_at": "2015-05-24 10:00 AM -0400",
              "updated_at": "2015-10-12 11:30 PM -0400"
            }
          ],
          "workflow_milestone_id": 1
        }
      ],
      "kind": "Contact",
      "visible_to": "Everyone"
    }
  ]
}

WorkflowTemplate¶

GET
Fetch an existing workflow template
`/v1/workflow_templates/{id}`

Retrieve a specific workflow template using it unique identifier. The workflow template returned will include the attributes listed below.

Parameters

id number, required: The id of the workflow template to be retrieved

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string: The name of the WorkflowTemplate
sequential boolean: Flag to determine if the workflow steps in this template must be completed in order of their position
description string: A short description of the WorkflowTemplate as plain text
description_html string: A short description of the WorkflowTemplate as html
shared boolean: Flag to determine if this WorkflowTemplate is shared amongst all accounts (workspaces) in the subscription
ready boolean: Flag to determine if this WorkflowTemplate is ready to spawn new Workflows
workflow_milestones Array (WorkflowTemplateMilestone): An array of all workflow milestones related to this WorkflowTemplate
workflow_steps Array (WorkflowStep): An array of all workflow steps related to this WorkflowTemplate
kind string: A string to classify the template

Choices: Contact Project Opportunity
visible_to string: The user group which is able to view the resource being created

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "New Client Onboarding Process",
  "sequential": true,
  "description": "Onboarding workflow for our clients...",
  "description_html": "<div>Onboarding workflow for our clients...</div>",
  "shared": true,
  "ready": true,
  "workflow_milestones": [
    {
      "id": "abcdef",
      "name": "Onboarding"
    }
  ],
  "workflow_steps": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "name": "Schedule discover meeting",
      "description": "In this meeting, we will...",
      "description_html": "<div>In this meeting, we will...</div>",
      "workflow": 1,
      "assigned_to": 1,
      "due_based_on": "default",
      "due_date_set": true,
      "due_later": "2 days later at 5:00 PM",
      "due_date": "2024-03-06 11:30 AM -0500",
      "priority": "None",
      "workflow_outcomes": [
        {
          "id": 1,
          "workflow_step_id": 1,
          "name": "Meeting scheduled with client",
          "action": "Go to Step",
          "go_to_step_id": 2,
          "due_date_set": false,
          "due_later": "2 days later at 5:00 PM",
          "created_at": "2015-05-24 10:00 AM -0400",
          "updated_at": "2015-10-12 11:30 PM -0400"
        }
      ],
      "workflow_milestone_id": 1
    }
  ],
  "kind": "Contact",
  "visible_to": "Everyone"
}

Complete a workflow step¶

PUT
Complete a workflow step
`/v1/workflows/{workflow_id}/steps/{id}`

Parameters

workflow_id number, required: The id of the workflow which owns the step
id number, required: The id of the workflow step to complete

Request Attributes

complete boolean: Flag, which if present upon a request, marks step complete
workflow_outcome_id number: The ID of the outcome to be applied
due_date_set boolean: When selecting an outcome with the “Restart Step” action, this indicates whether the restarted step will have a due date
due_date string: When selecting an outcome with the “Restart Step” action, this indicates the due date for the restarted step

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string: The name of the Workflow Step
description string: A short description of the WorkflowStep as plain text
description_html string: A short description of the WorkflowStep as html
workflow number: The ID of the Workflow this step is connected to
assigned_to number: The ID of the contact that is assigned to this workflow
due_based_on string: Indicates what this step’s due date is based on. Available options are “default”, “start” and “milestone”. If no option is specified this will be set to “default”. “milestone” means a workflow_milestone_id must be provided. “start” means the step is based on the workflow start date
due_date_set boolean: A flag indicating a due date is set for this WorkflowStep
due_later string: A string representing the interval of time when this workflow step is due after the start of a workflow
due_date Datetime: The specific deadline (due date) for an active or completed Workflow Step
priority string: The relative priority of the Workflow Step

Choices: None Low Medium High
workflow_outcomes Array (WorkflowOutcome): An array of all WorkflowOutcomes related to this Workflow Step
workflow_milestone_id number,null: The ID of the WorkflowMilestone this step is based on
completer number: The id of the user who completed the event

Request Complete a WorkflowStep

Body

{
  "complete": true,
  "workflow_outcome_id": 1,
  "due_date_set": true,
  "due_date": "2020-09-25 10:00 AM -0400"
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Schedule discover meeting",
  "description": "In this meeting, we will...",
  "description_html": "<div>In this meeting, we will...</div>",
  "workflow": 1,
  "assigned_to": 1,
  "due_based_on": "default",
  "due_date_set": true,
  "due_later": "2 days later at 5:00 PM",
  "due_date": "2024-03-06 11:30 AM -0500",
  "priority": "None",
  "workflow_outcomes": [
    {
      "id": 1,
      "workflow_step_id": 1,
      "name": "Meeting scheduled with client",
      "action": "Go to Step",
      "go_to_step_id": 2,
      "due_date_set": false,
      "due_later": "2 days later at 5:00 PM",
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400"
    }
  ],
  "workflow_milestone_id": 1,
  "completer": 1
}

Revert a workflow step¶

PUT
Revert a workflow step
`/v1/workflows/{workflow_id}/steps/{id}`

Parameters

workflow_id number, required: The id of the workflow which owns the step
id number, required: The id of the workflow step to revert

Request Attributes

revert boolean: Flag, which if present upon a request, reverts the complete status of a workflow step

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string: The name of the Workflow Step
description string: A short description of the WorkflowStep as plain text
description_html string: A short description of the WorkflowStep as html
workflow number: The ID of the Workflow this step is connected to
assigned_to number: The ID of the contact that is assigned to this workflow
due_based_on string: Indicates what this step’s due date is based on. Available options are “default”, “start” and “milestone”. If no option is specified this will be set to “default”. “milestone” means a workflow_milestone_id must be provided. “start” means the step is based on the workflow start date
due_date_set boolean: A flag indicating a due date is set for this WorkflowStep
due_later string: A string representing the interval of time when this workflow step is due after the start of a workflow
due_date Datetime: The specific deadline (due date) for an active or completed Workflow Step
priority string: The relative priority of the Workflow Step

Choices: None Low Medium High
workflow_outcomes Array (WorkflowOutcome): An array of all WorkflowOutcomes related to this Workflow Step
workflow_milestone_id number,null: The ID of the WorkflowMilestone this step is based on

Request Revert a WorkflowStep

Body

{
  "revert": true
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Schedule discover meeting",
  "description": "In this meeting, we will...",
  "description_html": "<div>In this meeting, we will...</div>",
  "workflow": 1,
  "assigned_to": 1,
  "due_based_on": "default",
  "due_date_set": true,
  "due_later": "2 days later at 5:00 PM",
  "due_date": "2024-03-06 11:30 AM -0500",
  "priority": "None",
  "workflow_outcomes": [
    {
      "id": 1,
      "workflow_step_id": 1,
      "name": "Meeting scheduled with client",
      "action": "Go to Step",
      "go_to_step_id": 2,
      "due_date_set": false,
      "due_later": "2 days later at 5:00 PM",
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400"
    }
  ],
  "workflow_milestone_id": 1
}

Collection¶

GET
Retrieve all events
`/v1/events{?resource_id}{?resource_type}`

This endpoint will fetch all of the events that are accessible by the user. This way the user can not access any events they don’t have access to.

Parameters

resource_id number: The id of the resource being searched for
resource_type string: The type of resource being searched for
startDateMin string: The minimum start date of the events to be returned
startDateMax string: The maximum start date of the events to be returned
order string: The order that the events should be returned in regarding event start

Choices: ascdescrecentcreated

Response Attributes

events Array (Event)

Response 200

Body

{
  "events": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "title": "Client Meeting",
      "starts_at": "2015-05-24 10:00 AM -0400",
      "ends_at": "2015-05-24 11:00 AM -0400",
      "repeats": true,
      "event_category": 2,
      "all_day": true,
      "location": "Conference Room",
      "description": "Review meeting for Kevin...",
      "state": "unconfirmed",
      "visible_to": "Everyone",
      "email_invitees": true,
      "linked_to": [
        {
          "id": 1,
          "type": "Contact",
          "name": "Kevin Anderson"
        }
      ],
      "invitees": [
        {
          "id": 1,
          "type": "User",
          "name": "Kevin Anderson"
        }
      ],
      "custom_fields": [
        {
          "id": 1,
          "name": "My Field",
          "value": "123456789",
          "document_type": "Contact",
          "field_type": "single_select"
        }
      ]
    }
  ]
}

POST
Create a new event
`/v1/events`

Create a new event

Request Attributes

title string, required: The name of the event being returned
starts_at Datetime, required: A timestamp signifying when the event starts
ends_at Datetime, required: A timestamp signifying when the event ends
repeats boolean: A flag to indicate whether or not the event repeats
event_category number: The id of the event category to which the event belongs
all_day boolean: A flag to indicate if the event lasts all day
location string: The description of the location the event takes place
description string: A short explaination of the event being returned
state string: The current state of the event

Choices: unconfirmed confirmed tentative completed cancelled
visible_to string: The user group which is able to view the resource being created
email_invitees boolean: A flag to indicate if the invitees should be emailed their invitation
linked_to Array (Document): An array of resources that are linked to this event. The only supported resource type is contact.
invitees Array (InviteeRequest): An object that describes a contact or user who is visiting the site
custom_fields Array (CustomFieldRequest): An array of custom fields for this object

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
title string, required: The name of the event being returned
starts_at Datetime, required: A timestamp signifying when the event starts
ends_at Datetime, required: A timestamp signifying when the event ends
repeats boolean: A flag to indicate whether or not the event repeats
event_category number: The id of the event category to which the event belongs
all_day boolean: A flag to indicate if the event lasts all day
location string: The description of the location the event takes place
description string: A short explaination of the event being returned
state string: The current state of the event

Choices: unconfirmed confirmed tentative completed cancelled
visible_to string: The user group which is able to view the resource being created
email_invitees boolean: A flag to indicate if the invitees should be emailed their invitation
linked_to Array (Document): An array of resources that are linked to this event. The only supported resource type is contact.
invitees Array (InviteeResponse): An object that describes a contact or user who is visiting the site
custom_fields Array (CustomField): An array of custom fields for this object

Request

Body

{
  "title": "Client Meeting",
  "starts_at": "2015-05-24 10:00 AM -0400",
  "ends_at": "2015-05-24 11:00 AM -0400",
  "repeats": true,
  "event_category": 2,
  "all_day": true,
  "location": "Conference Room",
  "description": "Review meeting for Kevin...",
  "state": "unconfirmed",
  "visible_to": "Everyone",
  "email_invitees": true,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "invitees": [
    {
      "id": 1,
      "type": "User"
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "value": "123456789"
    }
  ]
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "title": "Client Meeting",
  "starts_at": "2015-05-24 10:00 AM -0400",
  "ends_at": "2015-05-24 11:00 AM -0400",
  "repeats": true,
  "event_category": 2,
  "all_day": true,
  "location": "Conference Room",
  "description": "Review meeting for Kevin...",
  "state": "unconfirmed",
  "visible_to": "Everyone",
  "email_invitees": true,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "invitees": [
    {
      "id": 1,
      "type": "User",
      "name": "Kevin Anderson"
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ]
}

Event¶

GET
Fetch an existing event
`/v1/events/{id}`

Retrieve a specific event using it unique identifier. The event returned will include the attributes listed below.

Parameters

id number, required: The id of the event to be updated

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
title string, required: The name of the event being returned
starts_at Datetime, required: A timestamp signifying when the event starts
ends_at Datetime, required: A timestamp signifying when the event ends
repeats boolean: A flag to indicate whether or not the event repeats
event_category number: The id of the event category to which the event belongs
all_day boolean: A flag to indicate if the event lasts all day
location string: The description of the location the event takes place
description string: A short explaination of the event being returned
state string: The current state of the event

Choices: unconfirmed confirmed tentative completed cancelled
visible_to string: The user group which is able to view the resource being created
email_invitees boolean: A flag to indicate if the invitees should be emailed their invitation
linked_to Array (Document): An array of resources that are linked to this event. The only supported resource type is contact.
invitees Array (InviteeResponse): An object that describes a contact or user who is visiting the site
custom_fields Array (CustomField): An array of custom fields for this object

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "title": "Client Meeting",
  "starts_at": "2015-05-24 10:00 AM -0400",
  "ends_at": "2015-05-24 11:00 AM -0400",
  "repeats": true,
  "event_category": 2,
  "all_day": true,
  "location": "Conference Room",
  "description": "Review meeting for Kevin...",
  "state": "unconfirmed",
  "visible_to": "Everyone",
  "email_invitees": true,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "invitees": [
    {
      "id": 1,
      "type": "User",
      "name": "Kevin Anderson"
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ]
}

PUT
Update an existing event
`/v1/events/{id}`

Update a existing event with new properties, these properties will be saved to the database and the new event will be returned.

Parameters

id number, required: The id of the event to be updated

Request Attributes

title string, required: The name of the event being returned
starts_at Datetime, required: A timestamp signifying when the event starts
ends_at Datetime, required: A timestamp signifying when the event ends
repeats boolean: A flag to indicate whether or not the event repeats
event_category number: The id of the event category to which the event belongs
all_day boolean: A flag to indicate if the event lasts all day
location string: The description of the location the event takes place
description string: A short explaination of the event being returned
state string: The current state of the event

Choices: unconfirmed confirmed tentative completed cancelled
visible_to string: The user group which is able to view the resource being created
email_invitees boolean: A flag to indicate if the invitees should be emailed their invitation
linked_to Array (Document): An array of resources that are linked to this event. The only supported resource type is contact.
invitees Array (InviteeRequest): An object that describes a contact or user who is visiting the site
custom_fields Array (CustomFieldRequest): An array of custom fields for this object

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
title string, required: The name of the event being returned
starts_at Datetime, required: A timestamp signifying when the event starts
ends_at Datetime, required: A timestamp signifying when the event ends
repeats boolean: A flag to indicate whether or not the event repeats
event_category number: The id of the event category to which the event belongs
all_day boolean: A flag to indicate if the event lasts all day
location string: The description of the location the event takes place
description string: A short explaination of the event being returned
state string: The current state of the event

Choices: unconfirmed confirmed tentative completed cancelled
visible_to string: The user group which is able to view the resource being created
email_invitees boolean: A flag to indicate if the invitees should be emailed their invitation
linked_to Array (Document): An array of resources that are linked to this event. The only supported resource type is contact.
invitees Array (InviteeResponse): An object that describes a contact or user who is visiting the site
custom_fields Array (CustomField): An array of custom fields for this object

Request

Body

{
  "title": "Client Meeting",
  "starts_at": "2015-05-24 10:00 AM -0400",
  "ends_at": "2015-05-24 11:00 AM -0400",
  "repeats": true,
  "event_category": 2,
  "all_day": true,
  "location": "Conference Room",
  "description": "Review meeting for Kevin...",
  "state": "unconfirmed",
  "visible_to": "Everyone",
  "email_invitees": true,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "invitees": [
    {
      "id": 1,
      "type": "User"
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "value": "123456789"
    }
  ]
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "title": "Client Meeting",
  "starts_at": "2015-05-24 10:00 AM -0400",
  "ends_at": "2015-05-24 11:00 AM -0400",
  "repeats": true,
  "event_category": 2,
  "all_day": true,
  "location": "Conference Room",
  "description": "Review meeting for Kevin...",
  "state": "unconfirmed",
  "visible_to": "Everyone",
  "email_invitees": true,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "invitees": [
    {
      "id": 1,
      "type": "User",
      "name": "Kevin Anderson"
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ]
}

DELETE
Delete event
`/v1/events/{id}`

Delete an existing event from your account (workspace). This event will not be available to you going forward in the future.

Parameters

id number, required: The id of the event to be updated

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
title string, required: The name of the event being returned
starts_at Datetime, required: A timestamp signifying when the event starts
ends_at Datetime, required: A timestamp signifying when the event ends
repeats boolean: A flag to indicate whether or not the event repeats
event_category number: The id of the event category to which the event belongs
all_day boolean: A flag to indicate if the event lasts all day
location string: The description of the location the event takes place
description string: A short explaination of the event being returned
state string: The current state of the event

Choices: unconfirmed confirmed tentative completed cancelled
visible_to string: The user group which is able to view the resource being created
email_invitees boolean: A flag to indicate if the invitees should be emailed their invitation
linked_to Array (Document): An array of resources that are linked to this event. The only supported resource type is contact.
invitees Array (InviteeResponse): An object that describes a contact or user who is visiting the site
custom_fields Array (CustomField): An array of custom fields for this object

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "title": "Client Meeting",
  "starts_at": "2015-05-24 10:00 AM -0400",
  "ends_at": "2015-05-24 11:00 AM -0400",
  "repeats": true,
  "event_category": 2,
  "all_day": true,
  "location": "Conference Room",
  "description": "Review meeting for Kevin...",
  "state": "unconfirmed",
  "visible_to": "Everyone",
  "email_invitees": true,
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "invitees": [
    {
      "id": 1,
      "type": "User",
      "name": "Kevin Anderson"
    }
  ],
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ]
}

Collection¶

GET
Retrieve all opportunities
`/v1/opportunities{?resource_id}{?resource_type}{?order}`

This endpoint will fetch all of the opportunities that are accessible by the user. This way the user can not access any opportunities they don’t have access to.

Parameters

resource_id number: The id of the resource being searched for
resource_type string: The type of resource being searched for
order string: The order that the opportunities should be returned in

Choices: ascdescrecentcreated
include_closed boolean: Return won and lost opportunities as well

Response Attributes

opportunities Array (Opportunity)

Response 200

Body

{
  "opportunities": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "name": "Financial Plan",
      "description": "Opportunity to plan for...",
      "target_close": "2015-11-12 11:00 AM -0500",
      "probability": 70,
      "stage": 1,
      "manager": 1,
      "amounts": [
        {
          "amount": 56.76,
          "currency": "$",
          "kind": "Fee"
        }
      ],
      "linked_to": [
        {
          "id": 1,
          "type": "Contact",
          "name": "Kevin Anderson"
        }
      ],
      "visible_to": "Everyone",
      "custom_fields": [
        {
          "id": 1,
          "name": "My Field",
          "value": "123456789",
          "document_type": "Contact",
          "field_type": "single_select"
        }
      ]
    }
  ]
}

POST
Create a new opportunity
`/v1/opportunities`

Create a new Opportunity.

Request Attributes

name string, required: The name of the Opportunity being returned
description string: A short explaination of the opportunity being returned
target_close Datetime, required: A string representing the date/time when the opportunity should close
probability number, required: A number representing the chance the opportunity will close, as a percentage
stage number, required: A string representing the current stage the opportunity finds itself in
manager number: The id of the user who is designated as manager of this opportunity
amounts Array (Amount), required: An array of the amounts associated with the opportunity
linked_to Array (Document): An array containing the Contact that is linked to this Opportunity. Only the first contact specified will be used.
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomFieldRequest): An array of custom fields for this object

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the Opportunity being returned
description string: A short explaination of the opportunity being returned
target_close Datetime, required: A string representing the date/time when the opportunity should close
probability number, required: A number representing the chance the opportunity will close, as a percentage
stage number, required: A string representing the current stage the opportunity finds itself in
manager number: The id of the user who is designated as manager of this opportunity
amounts Array (Amount), required: An array of the amounts associated with the opportunity
linked_to Array (Document): An array containing the Contact that is linked to this Opportunity. Only the first contact specified will be used.
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomField): An array of custom fields for this object

Request

Body

{
  "name": "Financial Plan",
  "description": "Opportunity to plan for...",
  "target_close": "2015-11-12 11:00 AM -0500",
  "probability": 70,
  "stage": 1,
  "manager": 1,
  "amounts": [
    {
      "amount": 56.76,
      "currency": "$",
      "kind": "Fee"
    }
  ],
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "value": "123456789"
    }
  ]
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Financial Plan",
  "description": "Opportunity to plan for...",
  "target_close": "2015-11-12 11:00 AM -0500",
  "probability": 70,
  "stage": 1,
  "manager": 1,
  "amounts": [
    {
      "amount": 56.76,
      "currency": "$",
      "kind": "Fee"
    }
  ],
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ]
}

Opportunity¶

GET
Fetch an existing opportunity
`/v1/opportunities/{id}`

Retrieve a specific opportunity using it unique identifier. The opportunity returned will include the attributes listed below.

Parameters

id number, required: The id of the Opportunity to be updated

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the Opportunity being returned
description string: A short explaination of the opportunity being returned
target_close Datetime, required: A string representing the date/time when the opportunity should close
probability number, required: A number representing the chance the opportunity will close, as a percentage
stage number, required: A string representing the current stage the opportunity finds itself in
manager number: The id of the user who is designated as manager of this opportunity
amounts Array (Amount), required: An array of the amounts associated with the opportunity
linked_to Array (Document): An array containing the Contact that is linked to this Opportunity. Only the first contact specified will be used.
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomField): An array of custom fields for this object

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Financial Plan",
  "description": "Opportunity to plan for...",
  "target_close": "2015-11-12 11:00 AM -0500",
  "probability": 70,
  "stage": 1,
  "manager": 1,
  "amounts": [
    {
      "amount": 56.76,
      "currency": "$",
      "kind": "Fee"
    }
  ],
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ]
}

PUT
Update an existing opportunity
`/v1/opportunities/{id}`

Update a existing opportunity with new properties, these properties will be saved to the database and the new opportunity will be returned.

Parameters

id number, required: The id of the Opportunity to be updated

Request Attributes

name string, required: The name of the Opportunity being returned
description string: A short explaination of the opportunity being returned
target_close Datetime, required: A string representing the date/time when the opportunity should close
probability number, required: A number representing the chance the opportunity will close, as a percentage
stage number, required: A string representing the current stage the opportunity finds itself in
manager number: The id of the user who is designated as manager of this opportunity
amounts Array (Amount), required: An array of the amounts associated with the opportunity
linked_to Array (Document): An array containing the Contact that is linked to this Opportunity. Only the first contact specified will be used.
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomFieldRequest): An array of custom fields for this object

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the Opportunity being returned
description string: A short explaination of the opportunity being returned
target_close Datetime, required: A string representing the date/time when the opportunity should close
probability number, required: A number representing the chance the opportunity will close, as a percentage
stage number, required: A string representing the current stage the opportunity finds itself in
manager number: The id of the user who is designated as manager of this opportunity
amounts Array (Amount), required: An array of the amounts associated with the opportunity
linked_to Array (Document): An array containing the Contact that is linked to this Opportunity. Only the first contact specified will be used.
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomField): An array of custom fields for this object

Request

Body

{
  "name": "Financial Plan",
  "description": "Opportunity to plan for...",
  "target_close": "2015-11-12 11:00 AM -0500",
  "probability": 70,
  "stage": 1,
  "manager": 1,
  "amounts": [
    {
      "amount": 56.76,
      "currency": "$",
      "kind": "Fee"
    }
  ],
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "value": "123456789"
    }
  ]
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Financial Plan",
  "description": "Opportunity to plan for...",
  "target_close": "2015-11-12 11:00 AM -0500",
  "probability": 70,
  "stage": 1,
  "manager": 1,
  "amounts": [
    {
      "amount": 56.76,
      "currency": "$",
      "kind": "Fee"
    }
  ],
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ]
}

DELETE
Delete opportunity
`/v1/opportunities/{id}`

Delete an existing opportunity from your account (workspace). This opportunity will not be available to you going forward in the future.

Parameters

id number, required: The id of the Opportunity to be updated

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the Opportunity being returned
description string: A short explaination of the opportunity being returned
target_close Datetime, required: A string representing the date/time when the opportunity should close
probability number, required: A number representing the chance the opportunity will close, as a percentage
stage number, required: A string representing the current stage the opportunity finds itself in
manager number: The id of the user who is designated as manager of this opportunity
amounts Array (Amount), required: An array of the amounts associated with the opportunity
linked_to Array (Document): An array containing the Contact that is linked to this Opportunity. Only the first contact specified will be used.
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomField): An array of custom fields for this object

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Financial Plan",
  "description": "Opportunity to plan for...",
  "target_close": "2015-11-12 11:00 AM -0500",
  "probability": 70,
  "stage": 1,
  "manager": 1,
  "amounts": [
    {
      "amount": 56.76,
      "currency": "$",
      "kind": "Fee"
    }
  ],
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ]
}

Collection¶

GET
Retrieve all projects
`/v1/projects`

This endpoint will fetch all of the projects that are accessible by the user. This way the user can not access any projects they don’t have access to.

Response Attributes

projects Array (Project)

Response 200

Body

{
  "projects": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "name": "Client Seminar",
      "description": "Project to plan spring seminar.",
      "organizer": 1,
      "visible_to": "Everyone",
      "image": "https://app.crmworkspace.com/projects.png",
      "custom_fields": [
        {
          "id": 1,
          "name": "My Field",
          "value": "123456789",
          "document_type": "Contact",
          "field_type": "single_select"
        }
      ]
    }
  ]
}

POST
Create a new project
`/v1/projects`

Create a new Project.

Request Attributes

name string, required: The name of the project being returned
description string, required: A short explaination of the project being returned
organizer number: The id of the user who is responsible for organizating the project
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomFieldRequest): An array of custom fields for this object

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the project being returned
description string, required: A short explaination of the project being returned
organizer number: The id of the user who is responsible for organizating the project
visible_to string: The user group which is able to view the resource being created
image string: A expiring URL pointing to the headshot associated with the project valid for 7 days
custom_fields Array (CustomField): An array of custom fields for this object

Request

Body

{
  "name": "Client Seminar",
  "description": "Project to plan spring seminar.",
  "organizer": 1,
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "value": "123456789"
    }
  ]
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Client Seminar",
  "description": "Project to plan spring seminar.",
  "organizer": 1,
  "visible_to": "Everyone",
  "image": "https://app.crmworkspace.com/projects.png",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ]
}

Project Resource¶

GET
Fetch an existing project
`/v1/projects/{id}`

Retrieve a specific project using it unique identifier. The project returned will include the attributes listed below.

Parameters

id number, required: The id of the Project to be updated

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the project being returned
description string, required: A short explaination of the project being returned
organizer number: The id of the user who is responsible for organizating the project
visible_to string: The user group which is able to view the resource being created
image string: A expiring URL pointing to the headshot associated with the project valid for 7 days
custom_fields Array (CustomField): An array of custom fields for this object

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Client Seminar",
  "description": "Project to plan spring seminar.",
  "organizer": 1,
  "visible_to": "Everyone",
  "image": "https://app.crmworkspace.com/projects.png",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ]
}

PUT
Update an existing project
`/v1/projects/{id}`

Update a existing project with new properties, these properties will be saved to the database and the new project will be returned.

Parameters

id number, required: The id of the Project to be updated

Request Attributes

name string, required: The name of the project being returned
description string, required: A short explaination of the project being returned
organizer number: The id of the user who is responsible for organizating the project
visible_to string: The user group which is able to view the resource being created
custom_fields Array (CustomFieldRequest): An array of custom fields for this object

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the project being returned
description string, required: A short explaination of the project being returned
organizer number: The id of the user who is responsible for organizating the project
visible_to string: The user group which is able to view the resource being created
image string: A expiring URL pointing to the headshot associated with the project valid for 7 days
custom_fields Array (CustomField): An array of custom fields for this object

Request

Body

{
  "name": "Client Seminar",
  "description": "Project to plan spring seminar.",
  "organizer": 1,
  "visible_to": "Everyone",
  "custom_fields": [
    {
      "id": 1,
      "value": "123456789"
    }
  ]
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Client Seminar",
  "description": "Project to plan spring seminar.",
  "organizer": 1,
  "visible_to": "Everyone",
  "image": "https://app.crmworkspace.com/projects.png",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ]
}

DELETE
Delete project
`/v1/projects/{id}`

Delete an existing project from your account (workspace). This project will not be available to you going forward in the future.

Parameters

id number, required: The id of the Project to be updated

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
name string, required: The name of the project being returned
description string, required: A short explaination of the project being returned
organizer number: The id of the user who is responsible for organizating the project
visible_to string: The user group which is able to view the resource being created
image string: A expiring URL pointing to the headshot associated with the project valid for 7 days
custom_fields Array (CustomField): An array of custom fields for this object

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "name": "Client Seminar",
  "description": "Project to plan spring seminar.",
  "organizer": 1,
  "visible_to": "Everyone",
  "image": "https://app.crmworkspace.com/projects.png",
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "value": "123456789",
      "document_type": "Contact",
      "field_type": "single_select"
    }
  ]
}

Collection¶

GET
Retrieve all notes
`/v1/notes{?resource_id}{?resource_type}`

This endpoint will fetch all of the notes that are accessible by the user. This way the user can not access any notes they don’t have access to.

Parameters

resource_id number: The id of the resource being searched for
resource_type string: The type of resource being searched for
order string: The order that the resource should be returned in. “asc” (Assending by Created Date) is the default sort order. “created” is sort Decending by Created Date. “updated” is sort Decending by Updated Date.

Choices: asccreatedupdated

Response Attributes

notes Array (StatusUpdate)

Response 200

Body

{
  "notes": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "content": "Spoke with Kevin Anderson on the phone...",
      "linked_to": [
        {
          "id": 1,
          "type": "Contact",
          "name": "Kevin Anderson"
        }
      ],
      "visible_to": "Everyone",
      "tags": [
        {
          "id": 1,
          "name": "Clients"
        }
      ]
    }
  ]
}

POST
Create a new note
`/v1/notes`

Create a new Note.

Request Attributes

content string, required: The main body of the new StatusUpdate
linked_to Array (Document): An array of resources that are linked to this StatusUpdate. The only supported resource type is contact.
visible_to string: The user group which is able to view the resource being created
tags Array (string): An array of tags that are associated with the StatusUpdate

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
content string, required: The main body of the new StatusUpdate
linked_to Array (Document): An array of resources that are linked to this StatusUpdate. The only supported resource type is contact.
visible_to string: The user group which is able to view the resource being created
tags Array (Tag): An array of tags that are associated with the StatusUpdate

Request

Body

{
  "content": "Spoke with Kevin Anderson on the phone...",
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "visible_to": "Everyone",
  "tags": [
    "Clients"
  ]
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "content": "Spoke with Kevin Anderson on the phone...",
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "visible_to": "Everyone",
  "tags": [
    {
      "id": 1,
      "name": "Clients"
    }
  ]
}

Note¶

GET
Fetch an existing note
`/v1/notes/{id}`

Retrieve a specific note using it unique identifier. The note returned will include the attributes listed below.

Parameters

id number, required: The id of the Note to be updated

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
content string, required: The main body of the new StatusUpdate
linked_to Array (Document): An array of resources that are linked to this StatusUpdate. The only supported resource type is contact.
visible_to string: The user group which is able to view the resource being created
tags Array (Tag): An array of tags that are associated with the StatusUpdate

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "content": "Spoke with Kevin Anderson on the phone...",
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "visible_to": "Everyone",
  "tags": [
    {
      "id": 1,
      "name": "Clients"
    }
  ]
}

PUT
Update an existing note
`/v1/notes/{id}`

Update a existing note with new properties, these properties will be saved to the database and the new note will be returned.

Parameters

id number, required: The id of the Note to be updated

Request Attributes

content string, required: The main body of the new StatusUpdate
linked_to Array (Document): An array of resources that are linked to this StatusUpdate. The only supported resource type is contact.
visible_to string: The user group which is able to view the resource being created
tags Array (string): An array of tags that are associated with the StatusUpdate

Response Attributes

id number: The id of the object being returned
creator number: The id of the user who created the object
created_at Datetime: A timestamp representing when the object was created.
updated_at Datetime: A timestamp representing when the object was last updated.
content string, required: The main body of the new StatusUpdate
linked_to Array (Document): An array of resources that are linked to this StatusUpdate. The only supported resource type is contact.
visible_to string: The user group which is able to view the resource being created
tags Array (Tag): An array of tags that are associated with the StatusUpdate

Request

Body

{
  "content": "Spoke with Kevin Anderson on the phone...",
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "visible_to": "Everyone",
  "tags": [
    "Clients"
  ]
}

Response 200

Body

{
  "id": 1,
  "creator": 1,
  "created_at": "2015-05-24 10:00 AM -0400",
  "updated_at": "2015-10-12 11:30 PM -0400",
  "content": "Spoke with Kevin Anderson on the phone...",
  "linked_to": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ],
  "visible_to": "Everyone",
  "tags": [
    {
      "id": 1,
      "name": "Clients"
    }
  ]
}

List all contact roles¶

GET
List all contact roles
`/v1/categories/contact_roles`

This endpoint will fetch every contact role in the authenticated user’s account (workspace).

Response Attributes

contact_roles Array (ContactRole)

Response 200

Body

{
  "contact_roles": [
    {
      "id": 1,
      "name": "Planning Advisor",
      "available_options": [
        {
          "id": 1,
          "assigned_to": {
            "id": 1,
            "type": "User",
            "name": "Kevin Anderson"
          }
        }
      ],
      "removed_options": [
        {
          "id": 2,
          "deleted_at": "2022-06-30T00:00:00.000000+00:00",
          "assigned_to": {
            "id": 2,
            "type": "User",
            "name": "Maria Keston"
          }
        }
      ]
    }
  ]
}

List all custom fields¶

GET
List all custom fields
`/v1/categories/custom_fields`

This endpoint will fetch every custom field in the authenticated user’s account (workspace).

Request Attributes

document_type string: The document type that the custom fields are for, defaults to all document types

Choices: Contact Opportunity Project Task Event ManualInvestmentAccount

Response Attributes

custom_fields Array (CustomFieldConfig)

Request

Body

{
  "document_type": "Contact"
}

Response 200

Body

{
  "custom_fields": [
    {
      "id": 1,
      "name": "My Field",
      "document_type": "Contact",
      "field_type": "single_select",
      "options": [
        {
          "id": 1,
          "label": "Option one"
        }
      ]
    }
  ]
}

List all tags¶

GET
List all tags
`/v1/categories/tags`

This endpoint will fetch every tag in the authenticated user’s account (workspace).

Parameters

document_type string: The name of the document type that you are trying to fetch, defaults to All

Choices: ContactNote

Response Attributes

tags Array (TagWithDocumentType)

Response 200

Body

{
  "tags": [
    {
      "id": 1,
      "type": "Tag",
      "name": "Tag Name",
      "document_type": "Note"
    }
  ]
}

List all members of a customizable category¶

GET
List all members of a customizable category
`/v1/categories/{type}`

This endpoint will fetch every instance of the specified category name which are owned by the account (workspace) of the user authenticated with the API.

Parameters

type string, required: The name of the category type that you are trying to fetch

Choices: opportunity_stagesopportunity_pipelinescontact_typescontact_sourcestask_categoriesevent_categoriesfile_categoriesinvestment_objectivesfinancial_account_typesemail_typesphone_typesaddress_typeswebsite_typescontact_roles

Response Attributes

tags Array (Document)

Response 200

Body

{
  "tags": [
    {
      "id": 1,
      "type": "Contact",
      "name": "Kevin Anderson"
    }
  ]
}

Retrieve all comments¶

GET
Retrieve all comments
`/v1/comments{?resource_id}{?resource_type}`

This endpoint will fetch all of the comments that are accessible by the user for the specified resource.

Parameters

resource_id number: The id of the resource being searched for. Ignored if no resource_type provided
resource_type string: The type of resource being searched for

Response Attributes

comments Array (Comment)

Response 200

Body

{
  "comments": [
    {
      "id": 1,
      "creator": 1,
      "created_at": "2015-05-24 10:00 AM -0400",
      "updated_at": "2015-10-12 11:30 PM -0400",
      "body": {
        "text": "This is the body of the comment",
        "html": "<div class='comment'>This is the body of the comment</div>"
      },
      "resource_type": "Task",
      "resource_id": 1
    }
  ]
}

Create¶

POST
Add member to a household
`/v1/households/{household_id}/members`

This endpoint will add a member to the household.

Parameters

household_id number, required: The id of the household receiving the new member

Request Attributes

id number, required: The id of the contact to add to household
title string, required: The household title you wish to assign to the added contact

Choices: Head Spouse Partner Child Grandchild Parent Grandparent Sibling Other Dependent

Response Attributes

id number: The id of the household
members Array (string)

Request

Body

{
  "id": 2,
  "title": "Head"
}

Response 200

Body

{
  "id": 1,
  "members": [
    {
      "id": 2,
      "first_name": "Kevin",
      "last_name": "Anderson",
      "title": "Head",
      "type": "Person"
    }
  ]
}

Destroy¶

DELETE
Delete member from a household
`/v1/households/{household_id}/members/{id}`

This endpoint will remove a member from a household.

Parameters

household_id number, required: The id of the household from which the member will be deleted
id number, required: The id of the contact to delete from the household

Response Attributes

id number: The id of the household
members Array (string)

Response 200

Body

{
  "id": 1,
  "members": [
    {
      "id": 2,
      "first_name": "Kevin",
      "last_name": "Anderson",
      "title": "Head",
      "type": "Person"
    }
  ]
}

Retrieve all UserGroups¶

GET
Retrieve all UserGroups
`/v1/user_groups`

This endpoint will return all of the UserGroups associated with the account (workspace) of the user interacting with the API access token.

Response Attributes

user_groups Array (UserGroup)

Response 200

Body

{
  "user_groups": [
    {
      "id": 1,
      "name": "Everyone",
      "user": 1
    }
  ]
}

Retrieve all Teams¶

GET
Retrieve all Teams
`/v1/teams`

This endpoint will return all of the Teams associated with the account (workspace) of the user interacting with the API access token.

Response Attributes

teams Array (Team)

Response 200

Body

{
  "teams": [
    {
      "id": 1,
      "name": "Service",
      "members": [
        {
          "id": 1,
          "email": "bill@example.com",
          "name": "Bill Jones",
          "account": 1
        }
      ]
    }
  ]
}

Collection¶

GET
Retrieve all users
`/v1/users`

This endpoint will fetch all of the active users for the current account.

Response Attributes

users Array (User)

Response 200

Body

{
  "users": [
    {
      "id": 1,
      "email": "bill@example.com",
      "name": "Bill",
      "account": 1,
      "excluded_from_assignments": false
    }
  ]
}

Introduction¶

API Endpoint

Authentication¶

Authenticating with a personal API access token

Authenticating with OAuth

The basic flow of OAuth is as follows:

Example Request with API access token

Example Request with OAuth access token

Errors¶

HTTP Status Code Summary

Pagination¶

Example Request

Responses from the API¶

Successful response returning a single resource

Successful response returning a collection of resources

Unsuccessful response

Versioning¶

Example Request

Throttling¶

Retrieve login profile information¶

GETRetrieve login profile information/v1/me

Body

Retrieve activity stream¶

GETRetrieve activity stream/v1/activity{?contact}

Body

Retrieve all contacts¶

GETRetrieve all contacts/v1/contacts{?id}{?contactType}{?email}{?phone}{?type}{?name}{?active}{?householdTitle}{?order}{?tags}{?deleted}

Body

Create a new contact¶

POSTCreate a new contact/v1/contacts

Body

Body

Contact¶

GETFetch an existing contact/v1/contacts/{id}

Body

PUTUpdate an existing contact/v1/contacts/{id}

Body

Body

DELETEDelete an existing contact/v1/contacts/{id}

Body

Collection¶

GETRetrieve all tasks/v1/tasks{?resource_id}{?resource_type}{?assigned_to}{?assigned_to_team}{?created_by}{?completed}

Body

POSTCreate a new task and assign it to a user/v1/tasks

Body

Body

POSTCreate a new task and assign it to a team/v1/tasks

Body

Body

Task¶

GETFetch an existing task/v1/tasks/{id}

Body

PUTUpdate an existing task and assign it to a user/v1/tasks/{id}

Body

Body

PUTUpdate an existing task and assign it to a team/v1/tasks/{id}

Body

Body

DELETEDelete task/v1/tasks/{id}

Body

Collection¶

GETRetrieve all workflows/v1/workflows{?resource_id}{?resource_type}{?status}

Body

POSTCreate a new workflow/v1/workflows

Body

Body

Workflow¶

GETFetch an existing workflow/v1/workflows/{id}

Body

DELETEDelete workflow/v1/workflows/{id}

Body

Collection¶

GETRetrieve all workflow templates/v1/workflow_templates

Body

WorkflowTemplate¶

GETFetch an existing workflow template/v1/workflow_templates/{id}

Body

Complete a workflow step¶

PUTComplete a workflow step/v1/workflows/{workflow_id}/steps/{id}

Body

GET
Retrieve login profile information
`/v1/me`

GET
Retrieve activity stream
`/v1/activity{?contact}`

GET
Retrieve all contacts
`/v1/contacts{?id}{?contactType}{?email}{?phone}{?type}{?name}{?active}{?householdTitle}{?order}{?tags}{?deleted}`

POST
Create a new contact
`/v1/contacts`

GET
Fetch an existing contact
`/v1/contacts/{id}`

PUT
Update an existing contact
`/v1/contacts/{id}`

DELETE
Delete an existing contact
`/v1/contacts/{id}`

GET
Retrieve all tasks
`/v1/tasks{?resource_id}{?resource_type}{?assigned_to}{?assigned_to_team}{?created_by}{?completed}`

POST
Create a new task and assign it to a user
`/v1/tasks`

POST
Create a new task and assign it to a team
`/v1/tasks`

GET
Fetch an existing task
`/v1/tasks/{id}`

PUT
Update an existing task and assign it to a user
`/v1/tasks/{id}`

PUT
Update an existing task and assign it to a team
`/v1/tasks/{id}`

DELETE
Delete task
`/v1/tasks/{id}`

GET
Retrieve all workflows
`/v1/workflows{?resource_id}{?resource_type}{?status}`

POST
Create a new workflow
`/v1/workflows`

GET
Fetch an existing workflow
`/v1/workflows/{id}`

DELETE
Delete workflow
`/v1/workflows/{id}`

GET
Retrieve all workflow templates
`/v1/workflow_templates`

GET
Fetch an existing workflow template
`/v1/workflow_templates/{id}`

PUT
Complete a workflow step
`/v1/workflows/{workflow_id}/steps/{id}`

PUT
Revert a workflow step
`/v1/workflows/{workflow_id}/steps/{id}`

GET
Retrieve all events
`/v1/events{?resource_id}{?resource_type}`

POST
Create a new event
`/v1/events`

GET
Fetch an existing event
`/v1/events/{id}`

PUT
Update an existing event
`/v1/events/{id}`

DELETE
Delete event
`/v1/events/{id}`

GET
Retrieve all opportunities
`/v1/opportunities{?resource_id}{?resource_type}{?order}`

POST
Create a new opportunity
`/v1/opportunities`

GET
Fetch an existing opportunity
`/v1/opportunities/{id}`

PUT
Update an existing opportunity
`/v1/opportunities/{id}`

DELETE
Delete opportunity
`/v1/opportunities/{id}`

GET
Retrieve all projects
`/v1/projects`

POST
Create a new project
`/v1/projects`

GET
Fetch an existing project
`/v1/projects/{id}`

PUT
Update an existing project
`/v1/projects/{id}`

DELETE
Delete project
`/v1/projects/{id}`

GET
Retrieve all notes
`/v1/notes{?resource_id}{?resource_type}`

POST
Create a new note
`/v1/notes`

GET
Fetch an existing note
`/v1/notes/{id}`

PUT
Update an existing note
`/v1/notes/{id}`

GET
List all contact roles
`/v1/categories/contact_roles`

GET
List all custom fields
`/v1/categories/custom_fields`

GET
List all tags
`/v1/categories/tags`