Overview

Create your Developer Account

The first step in using the ToolCharm API is to create a developer account. This account will allow you to authenticate with the API and start making requests.

You can create your developer account here: Create Developer Account (opens in a new tab).

Once you create an account, navigate to the API Keys section to generate an API key. 100 free actions are provided to get you started and test the API.

You can click the lock icon to reveal/hide the API key.

You can click the copy icon to copy the API key to your clipboard.

Create an End User

End-users in ToolCharm are just another way to refer to your application's users. End-users are how we manage what integrations your users have connected to so we can perform actions on their behalf.

Here's how to create an End User in code:

curl -X POST https://api.toolcharm.com/endUsers \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY"

Here's the response of that request:

{
    "id": "00QHn000024LD2JMAW"
}

Authenticate with an Integration

The first step of authenticating user's in your application, is to get a list of all the supported integrations and their corresponsing authentication URLs. You need to pass the if of the end user you want to authenticate, so that we can properly store their keys.

Here's the code to get a list of all currently supported integrations:

curl -X GET 'https://api.toolcharm.com/integrations?endUserId=00QHn000024LD2JMAW' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY"

Here's the response of that request:

{
    "integrations": [
        {
            "id": 1,
            "name": "Salesforce",
            "logo": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRczw3_o3X38U8kfSw5UpPrNkuqMV26RKDy2w&s",
            "authenticationUrl": "https://salesforce.com/authenticate"
        }
    ]
}

You can also filter these integrations by passing in the type parameter to the body of the request.

Current integration types: crm

You should provide this list of integrations to your users, so they can authenticate with the services they use. The recommended way to do this is to provide a button that opens a new tab to the authentication URL.

For example, in React, you can use the following code to display the integrations and provide a button to authenticate with them:

import React from 'react';
 
const Integrations = ({ integrations }) => {
    return (
        <div>
            {integrations.map(integration => (
                <div key={integration.id}>
                    <h3>{integration.name}</h3>
                    <button onClick={() => window.open(integration.authenticationUrl, '_blank')}>Sign In to {integration.name}</button>
                </div>
            ))}
        </div>
    );
};

When a user completes this flow, they will successfully be authenticated with the service and they will be able to perform actions on that service.

You can run the following code to check if the user has successfully authenticated with the service:

curl -X GET https://api.toolcharm.com/endUsers/00QHn000024LD2JMAW \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY"

Here's the response of that request:

{
    "id": "00QHn000024LD2JMAW",
    "authenticatedIntegrations": ["Salesforce"]
}

Perform an Action

Now that you have authenticated an end-user, now we can perform an action! Here's the code to perform an action:

curl -X POST https://api.toolcharm.com/actions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "endUserId": "00QHn000024LD2JMAW",
  "action": "Create a new lead named John Doe who works at Acme Inc."
}'

Here's the response of that request:

{
    "serviceName": "Salesforce",
    "statusCode": 200,
    "apiResponse": {
        "id": "00QHn000024LD2JMAW",
        "firstName": "John",
        "lastName": "Doe",
        "company": "Acme Inc."
    },
    "textExtraction": {
        "firstName": "John",
        "lastName": "Doe",
        "company": "Acme Inc."
    },
    "timing": 2.43
}