API 3.0 Introduction

This documentation is for Version 3 of our API. See documentation for Version 2 of our API. Support for Version 2 is being phased out.

Sending/Receiving Data

The API can send and receive data in XML and JSON, as well as receive data as URL encoded query strings.

To send and receive XML or JSON you need to include the correct content-type header and replace the .format in the url.

Type Content-Type .format
JSON application/json .json
XML application/xml .xml

When sending a POST/PUT request with an empty body you need to make sure that the content-length header is present and set to zero, otherwise the API will throw an error. This is handled for you by most HTTP or Network libraries in most languages but some such as Python don't set the content-length header when sending an empty request body.

Partial Updates

You can partially update or create resources through our API by including the value partial=1 in the POST/PUT request’s body or url query string. This is the equivalent of using the emerging RESTful API standard’s PATCH method.

When creating a resource ‘partially’ using a POST request you don’t need to include all of the resource’s fields. All fields will be automatically set to null if they aren’t included. Note that the POST could still fail when partially creating a resource but not including the minimum required fields.

When updating a resource ‘partially’ using a PUT request any fields you don’t include will stay the same as before.

Warning: You need to exercise caution when updating sub resources of resources partially. If you tried only updating a contact’s phone numbers you need to include all phone numbers in the hash that you don’t want to be deleted, as we don’t extend the partial update feature to sub resources.

Sparse Responses

You can request sparse responses now by including the value sparse=1 in the PUT/POST request’s body or url query string for GET calls. This will give you a faster response as any empty fields will be completely omitted from the response body.

Beta Methods

Some methods are in Beta. You may find issues with these methods. Please post in our Developer Forum if you find any issues with these methods. Back To Top

API Endpoint

The API endpoint base url for all requests using the v3 API is:

https://app.onepagecrm.com/api/v3/
Back To Top

Request Parameters

You can configure your requests with standard HTTP parameters.
Just add them to HTTP query string for any request:

GET contacts.json?per_page=10&page=2

Or as part of HTTP request body for POST and PUT requests.

This section outlines the main parameters. To see all parameters supported by a particular resource, please visit that resource's section.

GET Paginating Responses

Whenever you are fetching a list of records, you can paginate the response with these standard parameters:

Type Name Description
integer page Page number. Starts from 1. Default is 1.
integer per_page Number of records to return. Maximum 100 allowed. Default is 10.

So, for example, to fetch first batch of 20 contacts:

GET contacts.json?per_page=20&page=1

To fetch second batch of 20 contacts, you would use:

GET contacts.json?per_page=20&page=2

GET Specifying the Fields You Need

Type Name Description
string fields Comma-separated lists of fields to return for each record.

fields parameter allows you to exclude data you don't need from response, include additional data that is not returned by default, and/or include associated resources to the response.
For detailed description of this parameter, see Fields section.

DELETE Undoing a Delete

Type Name Description
boolean undo Revert the deleting operation.

If you delete a contact or a tag with a DELETE request like this:

DELETE contacts/51f251d5eb899749f7000006.json

You can undo it by specifying an undo flag:

DELETE contacts/51f251d5eb899749f7000006.json?undo=1

GET POST PUT Switching Active User

Type Name Description
string user_id ID of a user on logged in user’s team.

Whenever you want to do something on behalf of logged in user’s teammate, use user_id parameter.

For example,

GET actions.json?user_id=51f251d5eb899749f7000006

would get actions for user with specified ID.

User ID specified in this parameter would also be used to populate any fields where otherwise logged in user’s ID would be default. For example, if you create a contact without specifying owner_id, but with user_id provided:

POST contacts.json?user_id=51f251d5eb899749f7000006&first_name=Jane&last_name=Doe

GETStripping Empty Fields

Type Name Description
boolean sparse Only include non-empty fields in the response.

If you specify the sparse flag, all fields which values are considered empty will be stripped from the response, even if they are specified in the fields parameter.

Values that are considered empty:

  • Empty string
  • Null
  • Boolean false
  • Empty array

Values that are not considered empty:

  • Integer or float zero
  • Empty hash (a hash for which all fields have been stripped)

POST PUT Providing Partial Data

Type Name Description
boolean partial Ignore all missing fields.

By default, all POST and PUT requests require all resource fields to be provided, otherwise throwing an error.
With partial flag set, If you don't provide a field then for POST requests it would be set to its default value (an empty string for most fields), and for PUT requests it would remain its current value.

For example the following request would update contact's name to Jane, leaving all other fields untouched:

PUT contacts/51f251d5eb899749f7000006.json?partial=1&first_name=Jane

And here is how you can create a contact named Jane Doe with all other fields set to their default values:

POST contacts.json?partial=1&first_name=Jane&last_name=Doe

Warning: Beware that if you use this option, any fields that you misspell or accidentally leave out from request will be ignored and their values would be lost, without any warnings or errors.
This is why, starting from version 3 of our API, partial POST requests are rejected by default, and this feature is active only if you specifically request it.

GET Limiting Listings By Time

When fetching collections, you can make them only return records that were modified in a given time range.

Type Name Description
time date_filter Filter returned data by a particular field when combined with since and until.
time since Return resources with dates in the provided date_filter parameter since this time. Otherwise it will return resources that were modified since this time.
time until Return resources with dates in the provided date_filter parameter until this time. Otherwise it will return resources that were modified until this time.
time unmodified_since Return only records that were unmodified since specified time.
time modified_since Return only records that were modified since specified time.

GET Avoiding Data You Already Have

Type Name Description
time if_modified_since Only return data if it could have been modified since specified time.

This parameter is similar to HTTP “If-Unmodified-Since” header, and will result in HTTP 304 “Not Modified” status returned if the data was not modified since the specified time.

Note that because of the complexity of our data, as well flexibility of API, if data is returned, it does not necessarily mean that it has been changed. If status 304 is returned however - it is guaranteed that the data has not been changed.

GET Sorting Listings By Field

Type Name Description
string sort_by Return records sorted by a particular field.

GET Order Listing By Field

Type Name Values Description
string order asc || desc Return records in a specified order, ascending or descending. If not specified, the default order is ascending.

GET Selecting Listings By Date Field

Type Name Description
string date_field Return records where their provided date field falls in a specific time.
Back To Top

Data Types

Our API works with following data types:

Type Description
string Text value. Leading and trailing spaces are removed.
bson_id Text value. This is a 24 character long string hexadecimal characters.
boolean In JSON, booleans are represented natively, in other formats, 0 for false and 1 for true are used.
integer In XML, integers are marked with type=”integer” attribute.
float In XML, floats are marked with type=”float” attribute.
date Dates are represented as strings in ISO 8601 format: ‘yyyy-mm-dd’.
Note: in case of actions, dates can also be ‘asap’ (infinitely close date) or ‘waiting’ (infinitely far date).
time Unix time, number of seconds since January 1st, 1970 UTC or ISO8601, YYYY-MM-DDThh:mm:ss.
We accept Unix timestamp but we only send out ISO8601 formatted strings.
array Ordered list of values.
In XML, arrays are marked with type=”array” attribute.
hash Associative array.
null Means “no value” (as opposed to “unknown value”). Note that empty strings and empty dates are considered as values and both represented as empty strings.
In XML, nulls are marked with nil=”true” attribute.
Back To Top

Response Format

Response can be sent in one of the following formats: JSON, XML

You must specify the format to be used for each request in a form of file extension:

/contacts.json
/contacts.xml

Each response is a hash. Only response time and status fields are always present.

HTTP Status Codes

Responses return with one of the following standard HTTP status codes:

Code Description
200 OK - Operation successful.
400 Bad Request. The request is not properly formatted, doesn’t properly specify response format or contains improper parameters or data.
401 Unauthorised. Authorization data is absent, invalid or expired. Generally this means that a login form should be displayed to a user.
403 Forbidden. Issued when user is logged in, but does not have permission for requested operation. This includes cases when user has reached limits like allowed number of contacts.
404 Resource Not Found. When an id was provided for a request but no resource exists for that object.
409 Precondition Failed. Server state does not allow requested operation to be carried on. Issued in cases such as when trying to add an assigned next action to a contact which already has one assigned for a user.
500 Internal Server Error.

The five error codes represent five main types of failures:

  • Code 400 means a problem is in your implementation. Fault is on you.
  • Code 401 means user just needs to login. Generally, fault is on no one.
  • Code 403 means operation is forbidden for a user. Fault is on user. Although in some cases, you could have prevented this by not sending the request in the first place.
  • Code 409 means the stars were not aligned for this to happen. Sometimes you could have foreseen it, sometimes not.
  • Code 500 means server messed up. Fault is on us.

Base Fields

Following fields are present in every response.

Type Name Description
integer status Duplication of HTTP response status for convenience
time timestamp Time of response

Failed Requests

These fields are present if a request has failed with a Client Error status (4xx).

Type Name Description
string error_name Short description of a failure to be used in your failure handling codes. You can see full lists of possible errors in every resource's section.
string error_message Human-readable description of a failure (meant for developers)
string more_info URL to documentation page describing the failure

Suppress HTTP Response Status

You can suppress the HTTP response status if required by adding a suppress_http_status=1 parameter to the end of your call. This will return a HTTP status of 200, but the response body will contain response codes and error detail.

For example the following request for a non existing contact will return HTTP status 404.

 https://app.onepagecrm.com/api/v3/contacts/1341.json

By adding the suppress_http_status=1 parameter, the call will return HTTP status 200.

 https://app.onepagecrm.com/api/v3/contacts/1341.json?suppress_http_status=1

Both requests will return the same body response:

{
  "status": 404,
  "message": "Resource not found",
  "error_name": "resource_not_found",
  "error_message": "Couldn't find contact for id, .\nThe contact may have been deleted or you may have used the wrong id"
}
Back To Top

Authentication

These methods allow you to gain access to to your account by providing you with an auth key in exchange for valid login credentials. There are also methods for logging out, changing your password and changing your auth key.

Login

URLs

Method Url Description
POST login.format Log in to your OnePageCRM account
GET bootstrap.format Get all the data that is returned with a login request

Request Fields

Type Name Description
string login Email address of user logging in
string password Password of the user logging in

Resource Fields

Type Name Description
string auth_key This is a base64 encoded string that you must use to sign further api requests.
string user_id ID of the user
string account_type Which type of account the user has. This will be one of: free, pro or trial.
array custom_fields A list of custom field objects that the user has. For more information visit the custom fields documentation page.
array filters User’s list of custom filters
object user User’s first name, last name, email, bcc email, company name and account rights. For more information visit the user documentation page.
array team A list of other users on the above user’s team. Each item is a user resource. For more information visit the user documentation page.
object settings User’s date format, reminders, currency, timezone, popular countries and contacts listing size. For more information visit the user settings documentation page.

Additional data

When logging in you will also receive additional data which provides information about a user’s account. This information includes statuses, lead sources, tags, sales data, team stream. This information is returned outside of the data object.

Type Name Description
array statuses List of status resources for the user’s account
array tags List of tag resources for the user’s account
array lead_sources List of lead sources for the user’s account
hash team_stream Every item is a hash with 2 elements:
Type Name Description
array users Every item is a hash with 2 elements:
Type Name Description
bson_id user_id id for user on this team
int counts total number of contacts the above user owns or has actions for.
int all total number of contacts this team has
This is used to convert the ‘stage’ field of deals into a string.
hash contacts_count This returns the number of total number of contacts, for each user and for the whole team, arranged by how many contacts have a last name beginning with each letter of the alphabet. Every item is a hash with 2 elements:
Type Name Description
array users Every item is a hash with 28 elements:
Type Name Description
bson_id user_id id for user on this team
int total_count total number of contacts the above user owns.
int 1 number of contacts with last name beginning with a number or special character
int a number of contacts with last name beginning with ‘a‘
  ...
int z number of contacts with last name beginning with ‘z’
hash all Every item is a hash with 27 elements:
Type Name Description
bson_id user_id id for user on this team
int total_count total number of contacts the team has
int 1 number of contacts with last name beginning with a number or special character
int a number of contacts with last name beginning with ‘a’
  ...
int z number of contacts with last name beginning with ‘z’
hash sales Every item is a hash with 4 elements:
Type Name Description
float target total sum of money targeted until the expiry date
float won total sum of money won since the start this periods
float pending total sum of money in pending deals
date expires date when the target expires
This is used to convert the ‘stage’ field of deals into a string.

Logout

URLs

Method Url Description
GET logout.format Invalidate auth key

WARNING

This will log the user out of all applications the user has logged into using this auth key. If you wish to log a user out just forget their auth key.
Note: this includes the mobile application.

Change Auth Key

URLs

Method Url Description
GET change_auth_key.format Invalidate auth key and return a new auth key

WARNING

This will log the user out of all applications the user has logged into using this auth key.
Note: this includes the mobile application.

Resource Fields

Type Name Description
string auth_key This is a base64 encoded string that you must use to sign further api requests.

Sample code

Sample JSON server response for bootstrap

URL: https://app.onepagecrm.com/api/v3/bootstrap.json

Back To Top

Login with Google - Beta

You can login to the OnePageCRM web application using a Google account. You can also authenticate with our API using your Google account.

There are three different endpoints you will need to work with to achieve this.

Step 1

In your API client, make a POST call to:

https://app.onepagecrm.com/api/v3/openid/init_session.json

The body of this post call should be like this:

{ "return_url": "https://onepagecrm.myclient.com" }

The return_url parameter is where you would like Google to redirect to after authentication

This call will return a response like this:

{"status" : 0,
 "message" : "OK",
 "timestamp" : 1403176957,
 "data" : 
  {"sid" : "3e7d0485-b586-4352-8aa5-92c31dadbdc4",
   "key" : "tcnIR_WTaGX6XQVyb2MC",
   "expires" : 1403180557
  }
}

Step 2

Next make a POST call to:

https://app.onepagecrm.com/api/v3/openid/login.json

The body of this post call should be like this:

{ "sid": "3e7d0485-b586-4352-8aa5-92c31dadbdc4" }

The sid parameter is the parameter received in Step 1.

This call will return a response like this:

{"status" : 0,
 "message" : "OK",
 "timestamp" : 1403177169,
 "data" : 
  {"url" : 
    "https://www.google.com/accounts/o8/ud?openid.ax.mode=fetch_request&openid.ax.required=email%2Cfirstname%2Clastname&openid.ax.type.email=http%3A%2F%2Faxschema.org%2Fcontact%2Femail&openid.ax.type.firstname=http%3A%2F%2Faxschema.org%2FnamePerson%2Ffirst&openid.ax.type.lastname=http%3A%2F%2Faxschema.org%2FnamePerson%2Flast&openid.claimed_id=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select&openid.identity=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0%2Fidentifier_select&openid.mode=checkid_setup&openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0&openid.ns.ax=http%3A%2F%2Fopenid.net%2Fsrv%2Fax%2F1.0&openid.ns.sreg=http%3A%2F%2Fopenid.net%2Fextensions%2Fsreg%2F1.1&openid.realm=http%3A%2F%2Flocalhost%3A3000%2F&openid.return_to=http%3A%2F%2Flocalhost%3A3000%2Fapi%2Fv3%2Fopenid%2Fgoogle_callback%3Fsid%3D3e7d0485-b586-4352-8aa5-92c31dadbdc4&openid.sreg.optional=email%2Cfullname"
  }
}

The url parameter is the URL redirect to the Google authentication page. Your client will need to redirect to this URL so the user can log in to their Google account. After login, the user will be redirected to the URL as specified in the return_url parameter from Step 1.

Step 3

Finally, make a POST call to:

https://app.onepagecrm.com/api/v3/openid/finalize_session.json

The body of this post call should be like this:

{ "sid" : "3e7d0485-b586-4352-8aa5-92c31dadbdc4",
  "key" : "tcnIR_WTaGX6XQVyb2MC"
}

The sid and key parameters are the parameters received in Step 1.

If everything has gone according to plan, this call will return a response similar to the response from bootstrap.json. This will include user_id and auth_key parameters, which can then be used for subsequent API calls.

Back To Top

Signing Process

Header Parameters

These parameters need to be included with every request made to the API other than the initial call to login.format.

Parameters Description
X-OnePageCRM-UID The user’s unique identification number(user_id), received after sending email and password to login.format.
X-OnePageCRM-TS The current timestamp in unix time (in seconds)
X-OnePageCRM-Auth SHA-256 of the authentication signature calculated for every request based on the data sent.

Authentication Signature

The signing process ensures that all API requests are secure, using a similar signing process to the OAuth standard. It is based on 5 separate variables:

  1. The user_id received from login.format.
  2. The current unix timestamp in seconds. This has to be the same as the value in the header field X-OnePageCRM-TS.
  3. The http request method name as an uppercase string, either “GET”, “POST”, “PUT” or “DELETE”.
  4. The SHA-1 hash of the full request url, written as a lowercase hex string.
  5. The SHA-1 hash of the raw request body. This is left out for GET or DELETE requests.

Calculating request signature value

The Request signature is a HMAC-SHA256 hash (written in hex using lowercase for a-f) of a string which consists of 4 (for GET and DELETE requests) or 5 (for PUT and POST requests) dot-separated elements, which are (in this exact order):

  1. X-OnePageCRM-UID header value
  2. X-OnePageCRM-TS header value
  3. HTTP request method name, uppercase (GET, POST, PUT or DELETE)
  4. SHA-1 (written in hex using lowercase for a-f) hash of the full request URL
  5. (only for PUT and POST requests) SHA-1 hash (written in hex using lowercase for a-f) has of the raw request body.

The HMAC-SHA256 signature is calculated using the API-KEY as the signing key. The API key as received from the API is Base-64 encoded, so it has to be decoded into whatever format the HMAC-SHA256 function you are using requires. Usually this is a byte array.

The resulting lowercase hex is the value for the X-OnePageCRM-Auth header field.

Example Signature

We want to edit a contact with an id of ‘4d91d3ea6381904e44000026’ and partially update his first and last name.

  • The full url for this request is: ‘https://app.onepagecrm.com/api/v3/contacts/4d91d3ea6381904e44000026.json?partial=1’
  • The raw request body to partially update the contact’s name is: ‘{"firstname":"John", "lastname":"Doe"}’
  • The request type in uppercase is: PUT
  • The unix timestamp used for this request is: 1401366488
  • The user id as received from the login function is: 4e0046526381906f7e000002
  • The api key as received from the login function is: AJfSRLr7uhsa9lOIgKQ4Vu72zzg3QTE7pJL2iSeA6Mo=

Now we have to build the string which we can then encode using the API_key. When converting strings to a SHA-1 hash they should be saved as strings of hex values with lowercase letters for ‘a’ to ‘f’.

  • The url has to be SHA-1 encoded resulting in: 813617379a1e9903964546d9668042cb39c5d73f
  • The request body has to be SHA-1 encoded resulting in: 9970204aa4ec9813b84652747b33142ac6dc2821
  • The format of the string to be encoded is formed by string together the user_id, timestamp, request type, SHA-1 hash of the url and SHA-1 hash of the post body. They have to be in this order and separated by dots. The sample string is: ‘4e0046526381906f7e000002.1401366488.PUT.813617379a1e9903964546d9668042cb39c5d73f.9970204aa4ec9813b84652747b33142ac6dc2821’

Finally the signature string has to be HMAC-SHA256 encoded using the API key as signing key. The API key is received from the login call as a base-64 encoded byte array, and most HMAC signing functions require the key to be in plain bytes. Some languages and libraries have methods for this conversion, others require the API key to first be converted to a hex string which can then be converted to a byte array. See the sample code below for details.

Here is the resulting signature for the sample values: ‘85b1bbf78139c7e98e79d6d1faf40eaad9332cf53f8dedc8c755deeab3d39211’

Sample Code

To help with the signing process we have written the functions for signing API calls in various languages.

Back To Top

Fields

Fields Parameter

The optional fields parameter is a powerful tool allowing you to do a handful of things:

  • Work with only the data you need.
  • Request complementary data for resources like total pending amount for contacts.
  • Request associated resources in the same request. For example, to include linked deals when getting contacts.

Basic Use

fields is a comma-separated list of field names you want returned.

id field, which identifies individual resources like contacts, is always returned for GET requests, so there is no point in specifying it unless it is the only field you want returned.

For example, to get contacts with only IDs, first names and last names, you would use a following request:

GET contacts.json?fields=first_name,last_name

Field Types

There are three types of fields in our API:

  1. Resource fields - These fields make up a resource, comprising its default fieldset. When you PUT or POST to a resource, only these fields are handled, all others are ignored.
  2. Complementary data - These fields can be added for GET requests, providing some additional data for convenience. For example, Contacts resource has a photo_url complementary field providing the url of the contact's photo. If provided in PUT or POST requests - these fields are ignored.
  3. Associated resources - These fields allow you to get resources that are linked to the resource you are fetching, in the same request. For example, if you fetch a contact, you can request to add its deals to the response. See the section below for more info on associated resources.

On each resource’s page, you can see a list of its main fields, as well as available complementary data and associated resources.

Fetching Associated Resources

In every resource’s section you can see a list of associated resources. For example, contacts can have actions, deals and notes associated with them. To grab those in the same request, just specify them as a field.
If you are familiar with SQL, this is similar to Left Outer Join operation.

So if you’d like to add deals to our basic example above, just use:

GET contacts.json?fields=first_name,last_name,deals()

all shortcut

If you want to receive associated resources in addition to a full default fieldset, you can use all shortcut which is the same thing as listing all default fields. The following request would return all default contact fields plus linked deals:

GET contacts.json?fields=all,deals()

Specifying fields for associated resources

Going further, you can specify which fields you want returned for associated resources. To limit deals’ data in previous example to only the fields you need, just list them in parentheses:

GET contacts.json?fields=all,deals(name,amount)

Chaining

Going even further than that, you can expand the fieldset for these associated resources, requesting resources that are linked down the chain.

For example, if you want to request a list of actions (actions stream) with contacts, plus deals and notes linked to those contacts, this is how you would do it:

GET actions.json?fields=all,contacts(all,deals(),notes())

And of course you can tweak fieldsets for all of those linked resources:

GET actions.json?fields=all,contacts(all,deals(name,amount),notes(text))

GET contacts.json?fields=notes(text),deals(name,amount),actions(all)

Back To Top

Action Stream

Method Url Note
GET action_stream.format Returns contacts with actions, sorted correctly
GET action_stream.format?has_actions=false Returns all contacts, sorted correctly

Action Stream is a special listing of contacts, with following differences:

  • All contacts with suitable actions are returned, others excluded. If user_id parameter is provided, list would consist of contacts with next action assigned to the user (not necessarily owned by him).. If user_id is not provided, contacts with assigned next actions or unassigned actions are returned.
  • Contacts are sorted by actions. So instead of an alphabetical order, contacts are sorted by action’s assignee presence (assigned first), action’s date and action’s last modification time. For contacts with multiple actions, only top action participates in sorting.
  • Returned data includes actions by default. Default value of fields parameter for this request is ”all,next_actions(all),next_action(all)”. You can still change the value to whatever suits your needs however.
  • Filtering by letter is removed, “waiting” is added. letter filtering parameter is not supported. However, you can use boolean waiting flag to limit results to contacts having an action with “waiting” date (assigned to a specified user if user_id parameter is provided).
  • With actions only. By default a call to actions.json will return only contacts with a next action. This can be overridden by changing the call to: actions.json?has_actions=false

URL: https://app.onepagecrm.com/api/v3/action_stream.json

{
  "status": 0,
  "message": "OK",
  "timestamp": 1401357078,
  "data": {
    "contacts": [
      {
        "contact": {
          "id": "53762162d4ca1a31d7000001",
          "owner_id": "536c9546d4ca1a56c8000003",
          "first_name": "Bunny",
          "last_name": "Bravo",
          "photo_url": "",
          "job_title": "Mama",
          "background": "",
          "urls": [

          ],
          "phones": [

          ],
          "emails": [
            {
              "type": "work",
              "value": "mamma@cn.co"
            }
          ],
          "status_id": "536c954fd4ca1a56c8000006",
          "status": "Lead",
          "starred": true,
          "lead_source_id": "",
          "type": "company",
          "company_name": "Cartoon Network",
          "company_id": "537b1df8d4ca1a55e2000001",
          "tags": [

          ],
          "custom_fields": [

          ],
          "modified_at": "2014-05-27T20:33:34Z",
          "address_list": [
            {
              "address": null,
              "city": null,
              "state": null,
              "zip_code": null,
              "country_code": null
            }
          ]
        },
        "next_actions": [
          {
            "id": "537b1eead4ca1a55e2000008",
            "assignee_id": "536c9546d4ca1a56c8000003",
            "contact_id": "53762162d4ca1a31d7000001",
            "text": "Call Mama",
            "date": "2014-05-20",
            "done": false,
            "modified_at": "2014-05-20T09:23:04Z",
            "status": "date"
          }
        ],
        "next_actions_count": 1,
        "next_action": {
          "id": "537b1eead4ca1a55e2000008",
          "assignee_id": "536c9546d4ca1a56c8000003",
          "contact_id": "53762162d4ca1a31d7000001",
          "text": "Call Mama",
          "date": "2014-05-20",
          "done": false,
          "modified_at": "2014-05-20T09:23:04Z",
          "status": "date"
        }
      },
      {
        "contact": {
          "id": "53761df7d4ca1a2c2f000042",
          "owner_id": "536c9546d4ca1a56c8000003",
          "first_name": "Johnny",
          "last_name": "Bravo",
          "photo_url": "",
          "job_title": "Model",
          "background": "Johny tried to hit on me",
          "urls": [
            {
              "type": "website",
              "value": "www.cartoonnetwork.com"
            }
          ],
          "phones": [
            {
              "type": "work",
              "value": "+555 555"
            }
          ],
          "emails": [
            {
              "type": "work",
              "value": "jb@cartoonnetwork.com"
            }
          ],
          "status_id": "536c954fd4ca1a56c8000006",
          "status": "Lead",
          "starred": false,
          "lead_source_id": "",
          "type": "company",
          "company_name": "Cartoon Network",
          "company_id": "537b1df8d4ca1a55e2000001",
          "tags": [

          ],
          "custom_fields": [

          ],
          "modified_at": "2014-05-20T09:19:12Z",
          "address_list": [
            {
              "address": null,
              "city": null,
              "state": null,
              "zip_code": null,
              "country_code": null
            }
          ]
        },
        "next_actions": [
          {
            "id": "537b1e10d4ca1a55e2000003",
            "assignee_id": "536c9546d4ca1a56c8000003",
            "contact_id": "53761df7d4ca1a2c2f000042",
            "text": "Johnny to call...",
            "done": false,
            "modified_at": "2014-05-20T09:19:12Z",
            "status": "waiting",
            "date": null
          }
        ],
        "next_actions_count": 1,
        "next_action": {
          "id": "537b1e10d4ca1a55e2000003",
          "assignee_id": "536c9546d4ca1a56c8000003",
          "contact_id": "53761df7d4ca1a2c2f000042",
          "text": "Johnny to call...",
          "done": false,
          "modified_at": "2014-05-20T09:19:12Z",
          "status": "waiting",
          "date": null
        }
      }
    ],
    "total_count": 2,
    "page": 1,
    "max_page": 1,
    "per_page": 10
  }
}
Back To Top

Actions

Main URLs

Method Url Description
GET actions.format?assignee_id={id}
users/{id}/actions.format
Get actions for a specified user (must be on logged in user’s team)
GET contacts/{id}/actions.format
actions.format?contact_id={id}
Get any actions associated with a contact
GET actions/{id}.format Get a single action
POST contacts/{id}/actions.format
actions.format?contact_id={id}
Create a new action for a contact
PUT actions/{id}.format Update an action
PUT actions/{id}.format?partial=1 Partially update an action

Action collections are sorted by completion time (not completed first), assignee presence (assigned first), action date and modification time. So that completed actions always go after open ones and unassigned open actions go after assigned open ones. Putting it simple, the order is as follows:

  1. Assigned open actions sorted by action date and modification time.
  2. Unassigned open actions sorted by modification time (unassigned actions don’t have a date).
  3. Completed actions sorted by completion time.

When listing all actions for a user, following actions are included:

  • Actions assigned to the user.
  • Unassigned actions associated with a contact owned by the user.

Shortcut Methods

Method Url Description
PUT actions/{id}/assign_to/{user_id}.format Assign action to a specified user (must be on logged in user’s team)
PUT actions/{id}/unassign.format Unassign Action
PUT actions/{id}/mark_as_done.format Marks action as completed
PUT actions/{id}/undo_completion.format Undo marking action as completed
PUT contacts/{id}/assign_predefined_action/{action_id}.format Assign a predefined action to a contact, accepts assignee_id as a param, as well as status and date to override value given for predefined action.

Resource Fields

Type Name Description
string id Action ID (read only).
time modified_at Action’s last modification time (read-only)
string contact_id ID of a contact this actions is associated with.
string assignee_id ID of user an action is assigned to. Empty if action is unassigned.
string date Action’s date. Either as 'yyyy-mm-dd' or nil when status is ‘no_date’.
string text Action’s text. Maximum 140 characters allowed.
string status Replaces next, waiting, has_date. Can be one of the following values: date, asap, waiting, no_date.
date done_date Date when action was completed, ‘yyyy-mm-dd’, nil when done is false.
bool done True if the action has been completed.

Listing Parameters

Following parameters are supported when fetching a list of actions:

Type Name Description
bool done True: return only done actions
False: return only open actions
Not present: return both done and open actions
string type Get only actions with the given status. Can be date, asap, waiting or no_date.
string contact_id Get all actions for a contact.
string assignee_id Get all actions assigned to a user.

Sample code

Sample JSON server response for actions

URL: https://app.onepagecrm.com/api/v3/actions.json?contact_id=523637e1391ba11500000255

>Top

Back To Top

Activities

Activities contain information concerning changes in a OnePageCRM account. This endpoint allows you to return those activities and filter them in a way that suits you.

URLs

Method Url Description
GET activities.format Get a list of activities
GET contacts/{id}/activities.format Get a list of activities for a contact
GET companies/{id}/activities.format Get a list of activities for a company
GET activities/{id}.format Get a single activity

Listing Fields

Following parameters are supported when fetching a list of Activities:

Type Name Description
string type Only get activities with a particular type. Types include: notes, contacts, emails, actions, deals, all
string sub_type Only get activities with a particular sub type. Sub types include: new_note, edited_note, new_deal, edited_deal, new_contact, edited_contact, deleted_contact, edited_action, new_email
bson_id company_id Filter activities by company
bson_id contact_id Filter activities by contact
time date_filter Filter returned data by a particular field when combined with since and until
time since Return resources with dates in the provided date_filter parameter since this time. Otherwise it will return resources that were modified since this time.
time until Return resources with dates in the provided date_filter parameter until this time. Otherwise it will return resources that were modified until this time.
time unmodified_since Return only records that were unmodified since specified time
time modified_since Return only records that were modified since specified time

Resource Fields

Type Name Description
bson_id id id of the activity
array contact_ids ids of the contacts affected by this activity
array resource_ids ids of the resources that were changed due to this activity
string full_name Name of the main contact that this activity applies to
string company_name Name of the main company that this activity applies to
string main_type Main type of activity that took place. More information can be found in the ‘Activity Types’ section below
string sub_type Sub type of activity that took place. More information can be found in the ‘Activity Types’ section below
time created_at Time when this activity too place
hash activity The activity that took place. The format of this hash depends on the type of activity that took place. More information can be found in the ‘Activity Field’ section

Activity Types

Following parameters are supported when fetching a list of actions:

Main Type Sub Type   Main Type Sub Type
deals new_deal   notes new_note
  edited_deal     edited_note
contacts new_contact   actions edited_action
  edited_contact   emails new_email
  deleted_contact      

Activity Field

  Type Name Description
notes hash note The note that triggered this activity. (note resource)
  array text_history A list containing the different revisions of the note text
  string type This is related to the subtype: new or edited
deals hash deal The deal that triggered this activity (deal resource)
  hash previous_deal The deal state before it was edited (deal resource)
  string type This is related to the subtype: new or edited
actions hash action The action that triggered this activity (action resource)
  hash previous_action The action state before it was edited (action resource)
  string type This is the type of activity that took place: new edited or done
emails hash email This item is a hash with 3 elements
contacts array fields_changed A list of fields that have been changed for the contacts in the contact_ids list
  array unassigned_tags A list of tags that have been unassigned from the contacts in the contact_ids list
  array assigned_tags A list of tags that have been assigned to the contacts in the contact_ids list
  array renamed_tags A list of tags that have been renamed for the contacts in the contact_ids list

Sample code

Sample JSON server response for activities

URL: https://app.onepagecrm.com/api/v3/activities.json

>Top

Back To Top

Contacts

Main URLs

Method Url Description
GET contacts.format Get a list of contacts
GET contacts/{id}.format Get a single contact
POST contacts.format Create a contact
PUT contacts/{id}.format Update a contact
PUT contacts/{id}.format?partial=1 Partially update a contact
DELETE contacts/{id}.format Delete a contact
DELETE contacts/{id}.format?undo=1 Undo contact’s deletion

Shortcut Methods

Method Url Description
PUT contacts/{id}/star.format Star a contact
PUT contacts/{id}/unstar.format Unstar a contact
PUT contacts/{id}/assign_tag/{tag_id}.format Add a tag to a contact by name or ID
PUT contacts/{id}/unassign_tag/{tag_id}.format Remove a tag from a contact by name or ID
PUT contacts/{id}/unassign_tag/{tag_id}.format Remove a tag from a contact by name or ID

Listing Parameters

Following parameters are supported when fetching a list of contacts:

Type Name Description
string search Search phrase. Only contacts having this phrase in first, last or company name will be returned.
string letter Only return contacts whose display name begins with a specified letter (case insensitive).
Special value “1” is used for listing contacts whose display name begins with a number.
Display name depends on contact’s type. For contacts with “company” type it is company_name, for “individual” contacts it is concatenation of first_name and last_name.
string tag Only return contacts with a specified tag attached.
string status_id Only return contacts with a specified status.
string lead_source_id Only return contacts with a specified lead source.
boolean starred True: Only return starred contacts.
False: Only return unstarred contacts.
Default: Returns both starred and unstarred.
boolean waiting True: Only return contacts which have a ‘waiting’ next action for logged in or selected user.
False: Only return contacts which don’t have a ‘waiting’ next action for logged in or selected user.
Default: Returns both contacts with and without a “waiting” next action.
string owner_id Return contacts owned by specified user. If not provided, contacts for current user are returned.
string email Search for contacts with matching email address. Search is case insensitive.
string url Search for contacts with matching url. Search is case insensitive, but must be an exact match - ie a search for http://www.example.com will not find a contact with url www.example.com
id custom_field_id ID of custom field the custom_field_value is filtering by.
string custom_field_value Value for a custom field to filter the contacts list by.
The custom_field_id needs to be included with this parameter.
bool team True: The whole team’s contacts will be given.
False, Default: Only the logged in user’s contacts will be given.
time modified_since Return only records that were modified since specified time.
time unmodified_since Return only records that were not modified since specified time.
integer per_page Number of records to return. Maximum 100 allowed. Default is 10.
integer page Page number. Starts from 1. Default is 1.

Resource Fields

Following parameters are supported when fetching a contact:

Type Name Description
string id Contact ID (read only)
time created_at Date the contact was created at (read-only)
time modified_at Contact’s last modification time (read-only)
string type Type of the contact ('company' or 'individual'). Default is the administrator's default.
string first_name First name - truncated to 24 characters.
string last_name Last name - truncated to 24 characters.
string company_name Company name
string job_title Contact’s job title
string status_id Contact’s status ID. Default is the ID for the 'lead' status
string status Contact’s status. Default is ‘lead’
array tags Tags attached to a contact
boolean starred true if a contact is starred
string owner_id Contact’s owner ID. Default is logged in user’s ID.
string address_list List of address hashes, each containing the following fields
Type Name Description
string address Contact’s Adress
string city Contact’s city
string state Contact’s state
string zip_code Contact’s zip code
string country_code Contact’s country as ISO country code
string background Contact’s description
string lead_source_id Contact’s lead source id
array phones Contact’s phones. Every item is a hash with 2 elements:
Type Name Description
string type Phone type ('work', 'mobile', 'home', 'direct', 'fax', 'skype' or 'other')
string value Phone number
array emails Contact’s email addresses. Every item is a hash with 2 elements:
Type Name Description
string type Email type ('work', 'home', or 'other')
string value Email address
array urls Contact’s URLs. Every item is a hash with 2 elements:
Type Name Description
string type URL type - ('website', 'blog', 'twitter', 'linkedin', 'facebook', 'google_plus' or 'other')
string value URL
array custom_fields Array of contact's custom fields. Every item is an object with 2 elements:
Type Name Description
object custom_field { 'id' : 'custom field id'}
string value Field's value
  'custom_fields' : [
    {       
      'custom_field' : {
        'id' : cf_id 
      },
      'value' : 'B'
    },
    {
      'custom_field' : {
        'id' : second_cf_id
      },
      'value' : 'Y'
    }
  ]

Сomplementary Data

The following data is not part of the resource, but it can be returned for GET requests if specified in fields parameter. If any of this data is provided with POST or PUT requests, it will be ignored.

Type Name Description
string photo_url URL to contact's photo

Associated Resources

Method Url Description
GET contacts/{id}/notes.format Get contact’s notes
GET contacts/{id}/deals.format Get contact’s deals
GET contacts/{id}/actions.format Get contact’s actions

You can also have associated resources attached to contacts when you GET the latter ones. Just specify one of the fields listed below in the fields parameter.

Type Name Description
array deals() Last 4 deals associated with a contact.
array notes() Last 4 notes associated with a contact.
array nextactions() List of all assigned next actions for a contact sorted by action date and modification time.
array unassignedactions() List of unassigned next actions for a contact sorted by modification time.
action nextaction() Active user's next action for a contact. Request this field in case you only need "that one next action to move a sale forward" for currently logged in user. If current user doesn't have a next action for this contact, this field is empty.
array completedactions() Last 4 completed actions for this contact sorted by completion time.

For example, to fetch a list of contacts containing only IDs, names and current user's next actions, you could use a following request (note that id is always included - no point specifying it in the list):

GET contacts.json?fields=firstname,lastname,companyname,nextaction()

Requesting nextaction() field doesn't remove that main next action from nextactions list, so you can request both fields if you like to have both full list of next actions and quick access to the main one.

<!-- Sample from GitHub -->

Sample code

Sample JSON server response for contacts
<!-- /Sample from GitHub -->

URL: https://app.onepagecrm.com/api/v3/contacts.json

>Top

Back To Top

Deals

Deals store information about a deal that is taking place or has closed. They contain data on the name of the deal, the amount of money the deal is worth, the number of months the deal will last for, when a deal is expected to close or when it was closed and notes about the deal.

Using this resource you can create new deals, update already existing deals, delete deals or list a single deal or list deals for an individual company, individual contact or by whether they were won lost or are still pending.

URLs

Method Url Description
GET deals.format Get most recently updated deals
GET deals.format?contact_id={contact_id}
contacts/{contact_id}/deals.format
Get a list of deals for a contact
GET deals.format?company_id={company_id}
companies/{company_id}/deals.format
Get a list of deals for a company
GET deals.format?status={status} Get deals with a particular status
GET deals/{id}.format Get a single deal
POST deals.format?contact_id={contact_id}
contacts/{contact_id}/deals.format
Create a deal
POST deals.format?contact_id={contact_id}&partial=1
contacts/{contact_id}/deals.format?partial=1
Create a deal with unprovided
fields filled with default values
PUT deals/{id}.format Update a contact
PUT deals/{id}.format?partial=1 Partially update a deal
DELETE deals/{id}.format Delete a deal

Listing Fields

Following parameters are supported when fetching a list of Deals:

Type Name Description
string status Return deals that have the provided status type. Status can be one of: won, lost or pending.
time date_filter Filter returned data by a particular field when combined with since and until.
time since Return resources with dates in the provided date_filter parameter since this time. Otherwise it will return resources that were modified since this time.
time until Return resources with dates in the provided date_filter parameter until this time. Otherwise it will return resources that were modified until this time.
time unmodified_since Return only records that were unmodified since specified time.
time modified_since Return only records that were modified since specified time.

Resource Fields

Following parameters are supported when fetching a list of contacts:

Type Name Description
bson_id id id of the deal (read only)
bson_id contact_id id of the contact this deal belongs to (read only)
object contact_info JSON object containing contact_name and company relating to deal (read only)
date date Date related to the deal’s creation
string name Name of the deal (required)
string text The text in the body of the deal
string author First name and first letter of last name of the author of the deal (read only)
float amount Total amount of money to be paid per month
int months Number of months the above amount will be paid for
float total_amount Product of amount and months (read only)
int stage What stage this deal is at. This can be converted to a label using the deal stages list in the settings resource.
string status Status of the deal this is one of won, lost or pending
date expected_close_date Date when the deal is expected to be closed
date closed_date Date that the deal was closed. This is set automatically when a deal is marked as won or lost (read only).

Additional Resources

Related notes can also be returned with a deal. They are returned as a resource just as they would be if you were to get notes for a contact. By default the notes will only return their id field. To get more information about the returned notes use the fields parameter.

For example you would also like to return notes with their text field and author you could make a request like the one below.

GET deals/abcdef1234567890abcdef12.json?fields=notes(text,author)

Sample response

Sample JSON server response for a call to deals.json
{
  "status": 0,
  "message": "OK",
  "timestamp": 1402476678,
  "data": {
    "deals": [
      {
        "deal": {
          "id": "539817b5eb8997481c000002",
          "contact_id": "53721750aa76206e8a000001",
          "contact_info": {
            "contact_name": "John Deer",
            "company": "John Deer Farm Machinery"
          },
          "owner_id": "52d3d90beb899776e400000e",
          "name": "Tractor Wheels",
          "text": "John Deer want 10k of tractor wheels",
          "date": "2014-06-11",
          "amount": 10,
          "total_amount": 10,
          "status": "pending",
          "stage": 10,
          "expected_close_date": "2014-06-11",
          "author": "Peter A.",
          "months": 1,
          "modified_at": "2014-06-11T08:48:31Z",
          "close_date": null
        },
        "related_notes": []
      }
    ],
    "total_count": 1,
    "page": 1,
    "max_page": 1,
    "per_page": 10
  }
}
Back To Top

Notes

Notes allow you to keep track of your interactions with a customer, include important information that will help you with that contact or store any other information you see fit.

Using this resource you can create a new note, update an existing note, delete an old note, attach a note to a deal or list notes for a company, contact or all notes made by your team.

URLs

Method Url Description
GET notes.format?contact_id={contact_id}
contacts/{contact_id}/notes.format
Get a list of notes for a contact
GET notes.format?company_id={company_id}
companies/{company_id}/notes.format
Get a list of notes for a company
GET notes/{id}.format Get a single note
POST notes.format?contact_id={contact_id}
contacts/{contact_id}/notes.format
Create a note
POST notes.format?contact_id={contact_id}&partial=1
contacts/{contact_id}/notes.format?partial=1
Create a note with unprovided
fields filled with default values
PUT notes/{id}.format
PUT notes/{id}.format?partial=1 Partially update a note
DELETE notes/{id}.format Delete a note

Listing Fields

Following parameters are supported when fetching a list of notes:

Type Name Description
time date_filter Filter returned data by a particular field when combined with since and until
time since Return resources with dates in the provided date_filter parameter since this time. Otherwise it will return resources that were modified since this time.
time until Return resources with dates in the provided date_filter parameter until this time. Otherwise it will return resources that were modified until this time.
time unmodified_since Return only records that were unmodified since specified time
time modified_since Return only records that were modified since specified time

Resource Fields

Type Name Description
bson_id id id of the note (read only)
bson_id contact_id id of the contact this note belongs to (read only)
date date Date related to the note’s creation
string text The text in the body of the note (required)
string author First name and first letter of last name of the author of the note (read only)
bson_id linked_deal_id null if there is no linked deal

Sample code

Sample JSON server response for notes

URL: https://app.onepagecrm.com/api/v3/notes.json?contact_id=523637e1391ba11500000255

>Top

Back To Top

Users

You can get useful information about other people on your team or you can update your own account information. If you are an administrator you can edit all of your team members details.

URLs

Method Url Description
GET users.format Get a list of users on your team
GET users/{id}.format Get information on a single user
PUT users/{id}.format Update a user
PUT users/{id}.format?partial=1 Partially update a user

NOTES:

  • You can only update your own user if you have administrator rights.
  • You can’t update the company name of any user unless you have administrator rights.
  • To update a user’s bcc email set bcc_email=‘new’ in the PUT and the user’s current bcc_email will be deactivated and a new one will be provided.

Resource Fields

Following parameters are supported when fetching a list of notes:

Type Name Description
string first_name First name of user
string last_name Last name of user
string company_name Name of the company that this user works for
(read only, except by administrator).
string email Email address (read only)
string bcc_email Email address of user’s dropbox
string photo_url Url of user’s profile picture (read_only)
array account_rights List of permissions this user has

NOTES:

You can change the bcc_email by setting the bcc_email to ‘new’ when updating a user.

Shortcut Methods

These methods make it easier to carry out assigning and unassigning actions to and from users.

Method Url Description
PUT users/{user_id}/assign_action/
{action_id}.format
Assign the action with id {action_id} to the user
with id {user_id}
PUT users/{user_id}/unassign_action/
{action_id}.format
Unassign the action with id {action_id} to the user
with id {user_id}

>Top

Back To Top

Companies

The companies endpoint mimics the company view of contacts in the web app. It allows changing the company name and getting contacts and other resources grouped by company.

Main URLs

Method Url Description
GET companies.format Get a list of companies
GET companies/{id}.format Get a single company
PUT companies/{id}.format Update a company

Resources

Only the company name can be changed. As there is no actual company object this only updates the company_name field for all contacts in the company.

Type Name Description
string id Company ID (read only)
string name Company name
int total_won_amount Total monetary amount of deals won with this company (read only)
int total_pending_amount Total monetary amount of deals pending with this company (read only)
int contacts_count Number of Contacts in this company (read only)

Associated Resources

You can also have associated resources attached to companies when you GET the latter ones.

Just specify one of the fields listed below in the fields parameter.

Type Name Description
array contacts First Ten Contacts associated with this company
array pending_deals Most recently updated pending deals associated with this company (limited to 10).

Sample code

Sample JSON server response for companies

URL: https://app.onepagecrm.com/api/v3/companies.json

>Top

Back To Top

Custom Fields

Custom fields can be viewed by any user but only created and updated by the Account Owner.

Important Note:

Updating a custom field through the API differs from updating through the App.
When you update the list of choices of a custom field with a type of multiple_choice or select_box all contacts with this custom_field filled out are updated. The existing selected choice(s) are replaced on the new ones based on their index.

Example:

multiple choice custom field with choices = [“a”, “b”, “c”, “d”] is updated to [“1”, “2”, “3”, “4”]
One contact had the field filled out with choices [“a”,”d”] selected. Now [“1”,”4”] will be selected for the contact after the update.

Similarly:

Old choices New choices Old selected New selected
[“a”,”b”,”c”,”d”] [“1”,”2”,”3”] [“a”,”b”,”c”,”d”] [“1”,”2”,”3”]
[“a”,”b”,”c”,”d”] [“3”,”4”] [“a”,”c”,”d”] [”3”]
[“a”,”b”,”c”,”d”] [“3”,”2”,”1”] [“b”,”d”] [”2”]

URLs

Method Url Description
GET custom_fields.format Get a list of custom fields
GET custom_fields/{id}.format Get a single custom field
POST custom_fields.format Create a custom field
PUT custom_fields/{id}.format Update a custom field
PUT custom_fields/{id}.format?partial=1 Partially update a custom field
DELETE custom_fields/{id}.format Delete a custom field

Resource Fields

Type Name Description
bson_id id ID of the custom field (read only)
string name Name of the custom field. Used for identification of custom fields.
string type Type of custom field. This can be one ofthe following: multiple_choice, select_box, single_line_text, multi_line_text, date or number
array choices An array of possible choices. This needs to be present only for custom fields of type multiple_choice or select_box

Sample code

Sample JSON server response for custom_fields

URL: https://app.onepagecrm.com/api/v3/custom_fields.json

>Top

Back To Top

Custom Filters

Custom filters allow you to query contacts in your own custom way. These filters can only be created inside the webapp but they can be used through the API to return exactly the contacts you want.

URLs

Method Url Description
GET filters.format Get a list of custom filters for this account
GET filters/{id}.format Get a single custom filter

Resource Fields

Type Name Description
bson_id id ID of the custom filter (read only)
string name Name of the custom filter. Used for identification of custom filters

Additional Data

When you get a single custom filter it also returns a list of contacts. They are returned as a resource list just as they would be if you were to get contacts through their own endpoint.

By default the contacts will only return their id field. To get more information about the contacts use the fields parameter.

 GET filters/{filter_id}.json?fields=contacts(firstname) 
Will return data in this format:
{
  "status": 0,
  "message": "OK",
  "timestamp": 1400239610,
  "data": {
    "filter": {
      "id": "536c954fd4ca1a56c8000037",
      "name": "Pending deals"
    },
    "contacts": [
      {
        "contact": {
          "id": "536c954fd4ca1a56c800001f",
          "first_name": "Joe"
        }
      }
    ],
    "total_count": 1,
    "page": 1,
    "max_page": 1,
    "per_page": 10
  }
}

You can also paginate, sort and filter contacts by dates. For more info check out the listing fields section of contacts.

Extra Fields

Type Name Description
array contacts List of contacts that match this filter
int page Which page of the contacts is returned with this request
int per_page Number of contacts returned per page
int max_page Total number of pages of contacts with this status
int total_count Number of contacts this user’s team has with this status

Sample code

Sample JSON server response for filters

URL: https://app.onepagecrm.com/api/v3/filters.json

>Top

Back To Top

Closing Sales Cycle - Beta

It is possible to close and reopen the Sales Cycle using the API. As these methods are put requests, it is important that the body of the request is not empty. When closing the sales cycle, you can add a closing comment.

Method Url Body Description
PUT contacts/{id}/close_sales_cycle.format { "comment" : "no interest" } Close the sales cycle
PUT contacts/{id}/reopen_sales_cycle.format { } Reopen the sales cycle
Back To Top

Lead Sources

Lead sources are a way for you to classify the source of any contact that you add to OnePageCRM. Using this resource you can create new lead sources so that you can classify exactly where any lead was pulled from. You can also manage your lead sources, get a list of your current lead sources and get all contacts with a particular lead source.

URLs

Method Url Description
GET lead_sources.format Get a list of lead sources
GET lead_sources/{id}.format Get a lead source and a list of contacts with this lead source
POST lead_sources/{id}.format Create a lead source
PUT lead_sources/{id}.format Update a lead source name
DELETE lead_sources/{id}.format Delete a lead source

NOTES:

Only managers can use the POST, PUT and DELETE methods
You can’t DELETE a lead source if there is only 1 remaining

Resource Fields

Type Name Description
string id Lead Source ID. This matches the lead_source field in contacts (read only).
string text Lead source text to be displayed.
string counts Number of contacts the api user has with this lead_source (read only).
string total_count Number of contacts this user’s team has with this lead_source (read only).
array team_counts Number of contacts with this lead_source grouped by user. Every item is a hash with 2 elements:
Type Name Description
string counts Number of contacts the following user has with this lead_source (read_only)
string user_id ID of one ot the api user’s team members (read_only)

Additional Data

When you get a single custom filter it also returns a list of contacts. They are returned as a resource list just as they would be if you were to get contacts through their own endpoint.

By default the contacts will only return their id field. To get more information about the contacts use the fields parameter. You can also paginate, sort and filter contacts by dates. For more info check out the listing fields section of contacts.

Extra Fields

Type Name Description
array contacts List of contacts that match this filter
int page Which page of the contacts is returned with this request
int per_page Number of contacts returned per page
int max_page Total number of pages of contacts with this status
int total_count Number of contacts this user’s team has with this status

Sample code

Sample JSON server response for lead sources.

URL: https://app.onepagecrm.com/api/v3/lead_sources.json

>Top

Back To Top

Contact Photo - Beta

Contact photos can be uploaded using the API. It takes a parameter 'image', which must be a Base64 encoded string.

The Base64 encoded string must be a Base64 encoded image file.

Images will be cropped to a square and resized to 73px.

URL

Method Url Description
PUT contacts/#{id}/contact_photo.json Update contact with this photo

Resource Fields

Type Name Description
Base64 Encoded jpg/png image A base64 encoded jpg or png image file

Response

{
  "status" : 0,
  "message" : "OK",
  "timestamp" : 1401350305,
  "data" : 
    {"contact" :
      {"id" : "5384753e1da41754eb000015",
       "photo_url" :
        "https://onepagecrm-uploads.s3.amazonaws.com/5384753e1da41754eb000015/1401350304000/5386e8a01da4170ce500000e.png"
      }
    }
}
Back To Top

Statuses

Statuses are a way of qualifying where your contacts are in your sales pipeline. This endpoint allows you to view statuses so that you can convert the status key returned with contacts to the actual text of the status. Managers have more control and can create new statuses, update the text, color and description or delete statuses.

URLs

Method Url Description
GET statuses.format Get a list of statuses
GET statuses/{id}.format Get a status and a list of contacts with this status
POST statuses/{id}.format Create a status
PUT statuses/{id}.format Update a status
PUT statuses/{id}.format?partial=1 Partially update a status
DELETE statuses/{id}.format Delete a status

NOTES:

Only managers can use the POST, PUT and DELETE methods
When a DELETE request succeeds all contacts with that status become leads

Resource Fields

Type Name Description
string id Status ID. This matches the status field in contacts (read only).
string text Status text to be displayed.
string description A description of what this status is for.
string color Six character hex representation of the status text color. A list of valid colors is below.
string counts Number of contacts the api user has with this status (read only).
string total_count Number of contacts this user’s team has with this status (read only).
array team_counts Number of contacts with this status grouped by user. Every item is a hash with 2 elements:
Type Name Description
string counts Number of contacts the following user has with this status (read_only)
string user_id ID of one ot the api user’s team members (read_only)

Additional Resources

When returning a single status it will also embed a contacts list resource within it. This will return the following fields along with those mentioned above.

By default the contacts will only return their id field. To get more information about the contacts use the fields parameter. You can also paginate, sort and filter contacts by dates. For more info check out the listing fields section of contacts.

Extra Fields

Type Name Description
array contacts An array containing contact resources
int page Which page of the contacts is returned with this request
int per_page Number of contacts returned per page
int max_page Total number of pages of contacts with this status
int total_count Number of contacts this user’s team has with this status

Valid Color Strings

Hex Color Hex Color Hex Color
666666 3399ff cc0000
f96600 000000 ff00ff
009900        

Sample code

Sample JSON server response for statuses

URL: https://app.onepagecrm.com/api/v3/statuses.json

>Top

Back To Top

Tags

Tags provide a means to classify contacts by however many tags you choose to attach to them. This endpoint allows you to manage your tags.

The methods here allow you to:

  • Get a list of all tags and information about how many contacts have that tag.
  • Get information about a single tag and the contacts associated with it.
  • Create a new tag where no contacts have it assigned to them yet.
  • Update the name of a tag and have that new name be reflected for all contacts with it.
  • Delete a tag and have it removed from all contacts.
  • Undo the deletion of a tag restoring it to all contacts who had it when it was deleted.

URLs

Method Url Description
GET tags.format Get a list of lead sources
GET tags/{name}.format Get a lead source and a list of contacts with this lead source
POST tags/{name}.format Create a new tag
PUT tags/{name}.format Update a tag name
DELETE tags/{name}.format Delete a tag. This removes that tag from all contacts that had it.
DELETE tags/{name}.format?undo=1 Undo deletion of a tag

NOTES: If you don’t urlencode the {name} then it is possible that an error will be thrown.

Resource Fields

Type Name Description
string name Status text to be displayed
string counts Number of contacts the api user has with this lead_source (read only)
string total_count Number of contacts this user’s team has with this lead_source (read only)

Additional Resources

When returning a single tag it will also embed a contacts list resource within it. This will return the following fields along with those mentioned above.

By default the contacts will only return their id field. To get more information about the contacts use the fields parameter.

 GET tags/VIP.json?fields=contacts(firstname) 
Will return data in this format:
    {
      "status": 0,
      "message": "OK",
      "timestamp": 1400240256,
      "data": {
        "name": "VIP",
        "counts": 1,
        "total_count": 1,
        "contacts": [
          {
            "contact": {
              "id": "536c954fd4ca1a56c800001f",
              "first_name": "Joe"
            }
          }
        ],
        "page": 1,
        "max_page": 1,
        "per_page": 10
      }
    }
    

Extra Fields

Type Name Description
array contacts An array containing contact resources
int page Which page of the contacts is returned with this request
int per_page Number of contacts returned per page
int max_page Total number of pages of contacts with this lead source
int total_count Number of contacts this user’s team has with lead source

Sample code

Sample JSON server response for tags

URL: https://app.onepagecrm.com/api/v3/tags.json

>Top

Back To Top

Utilities

Currencies

This returns a list of currencies accepted and used by OnePageCRM. When updating a currency you must use one of these.

URL

Method Url Description
GET currencies.format Get a list of currencies

Countries

This returns a list of countries used for addresses in OnePageCRM.

URL

Method Url Description
GET countries.format Get a list of countries

Time Zones

This returns a list of currencies accepted and used by OnePageCRM. When updating a currency you must use one of these.

URL

Method Url Description
GET time_zones.format Get a list of time zones

Resource Fields

You can use this to get a list of fields that can be returned for each resource type. This should be used in conjunction with the rest of the documentation but you could also use it to dynamically build object to store responses from the server.

URLs

Method Url Description
GET resource_fields.format Get a list of fields returned for each type of resource
GET resource_fields/{resource_name}.format Return fields for a single resource type

NOTES:

The supported resource names are: actions, activities, contacts, companies, currencies, custom_fields, deals, filters, lead_sources, notes, settings, statuses, predefined_actions, tags, time_zones, users.

Resource Fields

Type Name Description
array {resource_name} List of fields returned when getting this resource
Back To Top
Back To Top