Nimble is a relationship-focused CRM for your entire team. With customizable contact records and easy-to-use Kanban-style workflows, managing client information has never been simpler. Nimble effortlessly integrates with both Microsoft 365 and Google Workspace, gathering contacts and leads from all your platforms, while our automation tools handle the busy work. Focus on what matters most – growing your business and nurturing relationships, as Nimble streamlines your workflow for maximum productivity.

The document below offers an overview of currently available APIs & how to utilize them. If you're missing some APIs for an integration you want to build, please contact us at [email protected].

Currently available APIs:

• Contacts & Contact fields - managing contacts & custom fields.
• Deals & Deals Pipelines - managing deals, pipelines, and deal pipeline fields.
• Messages - reading and creating draft messages.

We are building the API with a few main use cases in mind: widgets/extensions to Nimble, web clients (including our own), mobile clients, and 2-way data integrations with other services. We aim to make an API that is simple to use, easy to read, and flexible.

Your feedback is greatly appreciated while we continue to shape our API offering.

This document will describe authorization flow that return the authorization token that allow to make requests to Nimble API and access resources to which access has been granted for user. For For authorization Nimble use OAuth 2.0 protocol with bearer tokens. All technical details can be read in RFC6749 and RFC6750, but you don't need to read them (unless you want to know more details on OAuth 2.0) every detail that need to obtain access token and use this token for requesting resource on behalf of user will be described in this document.

• User - Person who has an account inside Nimble and owner of resources to which API provide access

• Client - Service that request a token and want to make requests to the Nimble API on behalf of User

• Authorization server - Server that allow User to grant access for Client to use his resources

• Resource server - Server that returns User's resources to Client if it was granted for access by User

• Bearer token - Token that Client received after User has granted access. Possession of this token allows client to make requests to Resource server in order to receive Client's resources.

In order to create a Client for Nimble API you need to have to register your application in our DB and get Client Secret and Client Id. Its can be done on the page with this link: https://support.nimble.com/third-party-integrations/nimble-api-access/nimble-api-access. You probably have done this already.

For giving you a good overview of process we will use scheme and give a brief explanation to the each step on scheme. Steps are shown by the arrows and has a letters assigned to each step on scheme.

Let's go over a scheme step by step.

• Step A - You have some product (Client) that wants to use Nimble Data for some purposes. User wants to use Client and you need to retrieve a grant of user to operate the data from Nimble on his behalf. So, user has something that allows to initiate this process from Client.
• Step B - Your client open a page that points to Authorization Server providing a params specified on scheme. As a params, you need to send your API key and URI of client to which Authorization Grant Code will be returned. You also need to specify, which Scopes do you request from user. You should separate scopes with comma or plus sign. Scopes are: basic (User and Company info), contacts and deals
• Step C - Auth server using your API Key (Client Key) creates a link to which user will be directed and send a redirect response. User will be automatically redirected to the page where he can put his credentials and grant access. Note that now user is on side of Authorization Server.
• Step D - As soon as user finished a process of providing access, Authorization Server takes a redirect URI that you specified on step B and sends code to that URI.
• Step E - Using this code you make a application/x-www-form-urlencoded request to the Authorization Server where in body you put code retrieved on previous step, your Client Secret, Client Id and Grant Type you want to receive. It is always authorization code. For details see Request access token
• Step F - If everything is valid then you will receive response from server with Access Token and Refresh Token. Now you are able to do a requests to the Nimble API using Access Token until it valid. Using Refresh Token you will be able to renew this token without involving User second time. For details see: Token refresh.

You should use this request on step B of Authorization Process. You need to open a page for user with this endpoint and provide a Redirect URI on which your handler will be able to catch the code from Authorization Server that will be returned when User successfully grant you a permission to use Nimble API.

Endpoint:

GET https://app.nimble.com/oauth/authorize

Params:

• client_id - required - Your Client Key from Application Page.

• redirect_uri- required - URI where you have a handler who will catch a code and finish the Process, see note below.

• response_type - required - must be set to code. We don't support Implicit Flow, so code is the only available option now.

• scope - required - there are 3 scopes in Nimble: Basic (User & Company Info), Contacts and Deals. Send them as basic,contacts,deals of basic+contacts+deals.

  Please note, that main value for redirect URL is specified in application settings on developer portal. redirect_uri parameter in URL could be used only to overwrite path part in redirect URL. So, redirect_uri should have exactly same URI, as specified in application settings.

Example request:

GET https://app.nimble.com/oauth/authorize?client_id=5f96b5e9adaxzca93x1213123132&redirect_uri=https%3A%2F%2Fyourportal.com%2Fauth%2Fpassed&response_type=code

Successful response:

First, user will be redirected to the page on Authorization Server with hostname https://app.nimble.com/oauth/authorize

As soon as he provided his credentials, you will receive a request like listed below on your Redirect URI:

https://yourportal.com/auth/passed?code=LTM4M 

Error response:

If the request is missing or has incorrect parameters, the user-agent will be redirected back to the redirect URI provided. The redirection will contain parameters specifying the error.

Example Invalid Authorization Request Redirect:

http://www.myapp.com/oauth?error=invalid_request&error_description=Invalid%20URL

After selecting Login, the user will be validated. If user validation is successful, a consent page is displayed. If user validation is unsuccessful, the user-agent will be redirected to the redirect URI provided in the initial request. This redirection will include additional parameters specifying the error.

Example Unsuccessful Validation Redirect:

http://www.myapp.com/oauth?error=access_denied&error_descripton=Validation%20errors

If user click Deny on the grant permission page then another error will be sent.

Example Deny Consent Redirect:

http://www.myapp.com/oauth?error=access_denied&error_description=User%20denied%20access

To get OAuth app credentials, please email api-support@nimble.com and include the following:

• App Name
• App Description
• Redirect URL for oAuth callback

As soon as User complete step C your handler will catch step D. You need to listen for redirect on your Redirect URI. Code returned to you isn't access token yet! You still need to obtain the authorization token. Note, that this code is valid for a short period time and if you not intiate request to access token as soon as you receive a code then received code can become invalid and User will need to reinitiate a process once again. So, on step E you need to receive access to token for which user granted you.

The Client should use the authorization code obtained to request an access token. When requesting an access token, you SHOULD specify required data as form parameters. Client application secret is needed for client authentication. When specifying client_id and client_secret as form parameters, the Content-Type header MUST be set to application/x-www-form-urlencoded. Request should be done via HTTPS only.

Endpoint:

POST https://app.nimble.com/api/oauth/token

Parameters:

• grant_type - required - must be set to authorization_code. You need to receive an Access token.
• code - required - code that you received on step D. This code has a short-valid time, so initiate request for token as soon as you receive it.
• redirect_uri - required - redirect URI for your application. Should be equal to redirect_uri, provided during Requesting grant code
• client_id - required - your Client API key.
• client_secret - required --- your Client API secret key.

Headers:

• Content-Type: application/x-www-form-urlencoded; charset=UTF-8 - required - you need to specify this header always

Example Request:

POST /api/oauth/token HTTP/1.1
Host: app.nimble.com
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Body : client_id=5f96b5e9a6b7478e15ee574a426aa063&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth&code=LTM4M&grant_type=authorization_code&client_secret=89bb4ffb4f264bff

Successfull Response JSON:

{
    "access_token": "bf086611-9e97-4d11-9cd7-3c86dec0bbd4",
    "token_type": "bearer",
    "expires_in": 599,
    "refresh_token": "515ac59b-6518-49a2-81d6-54f91ee74c4a",
    "scope": "basic"
}

Now when we have Access Token Received you need to store it and use for any requests for Nimble Data on behalf of user. This process described in Making requests tutorial

The application uses the refresh token to extend the validity of the access token provided with the refresh token. When refreshing an access token, you should specify required data as a form parameters. Client application secret is needed for client authentication. Content-Type header must be set to application/x-www-form-urlencoded.

Parameters:

• client_id - Client identifier used to obtain the authorization code
• client_secret - Client secret code
• grant_type - Must be set to refresh_token
• refresh_token - Refresh token obtained from the access token request
• redirect_uri - required --- redirect URI for your application. Should be equal to redirect_uri, provided during Request grant code

Example Request:

POST /api/oauth/token HTTP/1.1
Host: https://app.nimble.com/
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

client_id=3e8471e7516a0c85ef35ab1d23f1bdf1&client_secret=737d10deba3fd124&grant_type=refresh_token&refresh_token=5f752714eddb07a3e41c2a3311f514e1&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth

Example Response:

{
    "access_token": "1d7bc7328b402f4826e17607e364bc6a",
    "expires_in": 559,
    "refresh_token": "f35c2165112fda74f79b408cc253485fcdfd888a"
}

For your convinience we created some examples:

Python authorization example. Actual code implementation on Python and Tornado

Ruby authorization example. Implementation of authorization process in Ruby

If you have any problems or want to submit feedback feel free to go to our support forum or email us at api-support@nimble.com

When you've received token, using the process described in Obtaining API key guide, you are ready to call Nimble API. You can use one of two ways, described below. They both are equal.

Authenticating your request with URL parameter

In order to use this token code you just add it into URL as request parameter with name access_token.

Endpoint:

Any of available endpoint of Nimble API

Params:

No matter what request POST, GET or any other HTTP method, just add an access_token as parameter to URL.

• access_token - required - put a token for user under this parameter.

Example Request:

POST https://api.nimble.com/api/v1/contact?access_token=e0f7b053200672c2ff6ede59c8e2bfc7

Successful Response:

All API responses described on their corresponding pages.

Authenticating your request with HTTP header

You can also pass your token in HTTP header Authorization in format: Bearer <your token>.

Example request:

PUT /api/v1/contact/4f60a873fcf7b752ed006b7a HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Authorization: Bearer c0b5f46631455b543c309b8cb18b8dae
Content-Type: application/json; charset=utf-8

{
    "fields": {
        "first name": [
            {
                "modifier": "", 
                "value": "1name"
            }
        ]
    }
}

Errors in Nimble are returned as a JSON dictionary with appropriate HTTP error codes and following keys:

message : Message about the error

code : Extended error code

Validation Error

Sent on invalid parameters. Returns with HTTP code 409 and code field equal to 245.

This response looks like common error dictionary:

{
    "message": "You can specify either `keyword` or `query` parameter, not both!", 
    "code": 245
}

On contact creation and update --- additional data is returned.

{
    "message": "Validation errors",
    "code": 245,
    "errors": {
        "first name": [{
            "message": "First name or last name field is required for person and should not be empty",
            "field_id": "5049f697a694620a07000043"
        }]
    }
}

Here errors are a dictionary, containing information about field that caused the error. Key is field name and values are extended error message and unique id of the field that caused the error.

Quota Error

Sent if user exceeded his quota values. Returns with HTTP code 402 and code field equal to 108.

{
    "message": "You have created the maximum number of contact records allowed for your subscription.\nDon't worry, you can upgrade your account and add more contacts right now.", 
    "code": 108
}

Server error

Sent if unrecoverable Nimble server occurs. Returns with HTTP code 500 and code field equal to 107.

{
    "message": "Internal error handling request", 
    "code": 107
}

NotFound Error

Sent on attempt to get some object by invalid identifier (in most cases identifier of object is its ID in our database).

This response will contain dictionary with object_type and object_id fields:

{
    "object_type": "contact field",
    "object_id": "111111111111111111111111"
}

User management

Typical response to this request is a dictionary with 2 keys (unless otherwise specified by the specific API): meta and resources.

This field usually contains all data for the contacts you've requested. Here is an example of a Nimble contact

"resources": [
    {
        "updated": "2012-09-07T16:49:56+0300",
        "created": "2012-09-07T16:49:56+0300",
        "fields": {
            "description": [
                {
                    "value": "description",
                    "label": "description",
                    "modifier": "other"
                },
                {
                   "value": "description",
                   "label": "description",
                   "modifier": "linkedin"
                }
            ],
            "last name": [
                {
                    "modifier": "",
                    "value": "Akopyan",
                    "label": "last name"
                }
            ],
            "phone": [
                {
                    "modifier": "mobile",
                    "value": "+7 (917) 202-456-1111",
                    "label": "phone"
                },
                {
                    "modifier": "home",
                    "value": "+7 244 231 84 22",
                    "label": "phone"
                }
            ],
            "URL": [
                {
                    "modifier": "other",
                    "value": "https://nimble.com",
                    "label": "URL"
                },
                {
                    "modifier": "other",
                    "value": "https://app.nimble.com",
                    "label": "URL"
                }
            ],
            "source": [
                {
                    "modifier": "",
                    "value": "csv",
                    "label": "source"
                }
            ],
            "address": [
                {
                    "modifier": "other",
                    "value": "{'city': 'Dushanbe', 'street': 'First str. 15', 'zip': '54055', 'country': 'Farganistan'}",
                    "label": "address"
                }
            ],
            "email": [
                {
                    "modifier": "other",
                    "value": "[email protected]",
                    "label": "email"
                }
            ],
            "first name": [
                {
                    "modifier": "",
                    "value": "Amayak",
                    "label": "first name"
                }
            ]
        },
        "object_type": "contact",
        "id": "5049fb849b85f669e40000dc",
        "last_contacted": {
            "user_id": "5c459c52ceee1868ee3ab41f",
            "deletion_tstamp": null,
            "type": "LCType<message>",
            "object_id": "ed5afbee-37f5-db6b-7f71-c7d6b8750bbb",
            "tstamp": "2019-01-22T21:57:30+0000"
        },
        "avatar_url": "https://app.nimble.com/api/contacts/avatars/5049fb849b85f669e40000dc",
        "record_type": "person",
        "creator": "Emil Kio",
        "children": [],
        "tags": [
            {
                "tag": "csv import",
                "id": "5049fa0c9b85f62cb4000639"
            }
        ],
        "owner_id": "5049f696a694620a0700001c"
    }
]

Here is a description of the response in detail:

updated

: Timestamp of contact's last update time

created

: Timestamp of contact's creation time

fields

: Dictionary containing contact's fields data. Keys are field names and values are lists of field values. All default contact fields are described here

object_type

: String specifying document type. For contacts it's contact.

id

: Unique contact id in BSON format.

last_contacted

:

Information about last outbound message to this contact (if any). Contains following fields.

:   -   *user_id* --- unique id of owner in BSON format
    -   *object_id* --- id of object of corresponding type in BSON
        format
    -   *type* --- last contacted provider\'s type
    -   *tstamp* --- timestamp of last outbound message
    -   *deletion_tstamp* --- timestamp of object deleting

avatar_url

: URL of image that can be used as contact's avatar. Value of null is used to indicate that contact has no avatar associated.

record_type

: Type of contact. This can have one of two values: person and company.

creator

: Name of the person who created the contact

children

: For company contacts this field contains list of person contacts associated with the company.

tags

:

List of tags associated with the contact. Each tag is represented as a dictionary having following keys.

:   -   *tag* --- tag\'s text
    -   *id* --- unique id of tag in BSON format

owner_id

: Id of the person owning the contact in BSON format

Contact list request is similar to contact details response. It has the same key with resources, described here. Difference is in meta key value. For contact listing it returns pagination details.