Authentication

You can obtain your API keys from the 'API Keys' screen (see organization settings).

There are two keys:

  • A secret key for server-side use.
  • A public key for client-side use. This key can only be used by also setting a referrer domain.

Careful!

Do not expose the secret key in client-side code and don't commit it to your source code versioning repository.

Secret key usage

The secret key can be used in bearer token authentication:

  curl --request POST \
  --url https://api.sprouted.app/api/v1/customers \
  --header 'authorization: Bearer sk_...' \
  ...

Replace sk_... by your secret API key.

Public key usage

The public key can be used by passing it as a URL parameter:

  https://app.sprouted.app/api/v1/customers/?public_key=pk_...

Replace pk_... by your public API key.

Important — you must also set a so-called referrer domain from which you're going to make client-side calls to the Sprouted API. This domain can be entered in your organization's API Keys screen.

Errors

400 Bad Request is returned for invalid requests. In most cases the response contains an error description.

Customer

Call the customer API endpoint whenever a new user is created in your application.

The following attributes are supported:

  • customer -> id - your internal customer/user ID (optional)
  • customer -> email_address - the user's email address (required)
  • customer -> name -> full - the user's full name (required*)
  • customer -> name -> first - the user's first name (required*)
  • customer -> name -> last - the user's last name (required*)
  • customer -> encrypted_fields - comma-separated list of encrypted field names

Providing external_identifier is optional. If you provide one you can refer to the customer using this ID instead of the ID created by the Sprouted API.

You must either provide full or provide first and/or last name but you can't leave all name fields empty.

Note: only the full attribute can be encrypted at this time.


Create customer
Example request:
  curl --request POST \
  --url https://api.sprouted.app/api/v1/customers \
  --header 'authorization: Bearer sk_...' \
  --header 'content-type: application/json' \
  --data '{
  "customer": {
    "name": {
      "first": "Joe",
      "last": "Doe"
    },
    "email_address": "joe.doe@example.com"
  }
}'

A successful response returns 201 Created.

Example response:
  { "id": "{customer-id}" }

Update customer

Update an existing customer by passing its internal or external ID.

  curl --request PUT \
  --url https://api.sprouted.app/api/v1/customers/{internal-or-external-customer-id} \
  --header 'authorization: Bearer sk_...' \
  --header 'content-type: application/json' \
  --data '{
  "customer": {
    "email_address": "joe.doe.new.address@example.com"
  }
}'

A successful response returns 200 OK.

Example response:
  { "id": "{customer-id}" }

Delete customer

Delete an existing customer by passing its internal or external ID.

Example request:
  curl --request DELETE \
  --url https://api.sprouted.app/api/v1/customers/{internal-or-external-customer-id} \
  --header 'authorization: Bearer sk_...' \
  --header 'content-type: application/json'
}'

A successful response returns 200 OK.

Example response:
  {}

Encryption

You can pass encrypted fields to Sprouted. At this time only the full attribute can be encrypted. The secret-key cryptography of Sprouted is based on Libsodium.

Typical encryption flow:

  • Set the full attribute to the encrypted full name.
  • Set the encrypted_fields attribute to full.
  • Look at the newly added customer in Sprouted. The user's name is displayed as a string of hex codes i.e. gibberish.
  • Install the Sprouted browser extension. Enter the encryption key in the options screen.
  • Reload the customer page. The name is now readable!

Encryption code example:

  require 'rbnacl'

key = RbNaCl::Random.random_bytes(RbNaCl::SecretBox.key_bytes)
secret_box = RbNaCl::SecretBox.new(key)
nonce = RbNaCl::Random.random_bytes(secret_box.nonce_bytes)
encrypted_text = secret_box.encrypt(nonce, 'Yay, it works!')

hey_key = RbNaCl::Util.bin2hex(key)
hex_nonce = RbNaCl::Util.bin2hex(nonce)
hex_encrypted_text = RbNaCl::Util.bin2hex(encrypted_text)

Enter the hey_key value in the options screen of the browser extension.

Customer Event

Use the customer event API endpoint to record important customer events.

Examples of customer events:

  • Your user starts to use a key feature
  • The user upgrades or downgrades to another plan
  • The user resets her password
  • The user closes her account

When you're using the inbound email feature of Sprouted then events are created for every new email sent by the user. Events created by you via the API and inbound message events are combined into a single timeline of events per customer.

The following attributes are supported:

  • event -> type - event type i.e. its label or name
  • event -> properties - array of key-value pairs and data types
  • event -> properties -> data - key-value pair
  • event -> properties -> data_type - type of value (string, internal, Boolean)

Create customer event
Example request:
  curl --request POST \
  --url https://api.sprouted.app/api/v1/customers/{internal-or-external-customer-id}/events \
  --header 'authorization: Bearer sk_...' \
  --header 'content-type: application/json' \
  --data '{
  "event": {
    "type": "plan-change",
    "properties": [{
      "data": {
        "previous-plan": "free"
      },
      "data_type": "string"
    }, {
      "data": {
        "new-plan": "pro"
      },
      "data_type": "string"
    }]
  }
}'

A successful response returns 201 Created.

The contents of the type attribute will be converted to lower case and spaces converted to dashes.

The properties attribute holds an array of key-value pairs and a data_type attribute which defines the value type. Supported data types are string, number, and Boolean. If you omit the data type then string is assumed. Pass true or false as Boolean values.

Example response:
  { "id": "{customer-event-id}" }

HTTP code examples

The examples below show how to perform http POSTs in several popular languages:

C# (with RestSharp)

  var client = new RestClient("https://app.sprouted.app/api/v1/customers");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Bearer sk_...");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\n  \"customer\": {\n    \"name\": {\n      \"first\": \"Joe\",\n      \"last\": \"Doe\"\n    },\n    \"email_address\": \"joe.doe@example.com\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Go

  package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://app.sprouted.app/api/v1/customers"

  payload := strings.NewReader("{\n  \"customer\": {\n    \"name\": {\n      \"first\": \"Joe\",\n      \"last\": \"Doe\"\n    },\n    \"email_address\": \"joe.doe@example.com\"\n  }\n}")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("authorization", "Bearer sk_...")
  req.Header.Add("content-type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

Java (with Unirest)

  HttpResponse response = Unirest.post("https://app.sprouted.app/api/v1/customers")
  .header("authorization", "Bearer sk_...")
  .header("content-type", "application/json")
  .body("{\n  \"customer\": {\n    \"name\": {\n      \"first\": \"Joe\",\n      \"last\": \"Doe\"\n    },\n    \"email_address\": \"joe.doe@example.com\"\n  }\n}")
  .asString();

JavaScript (with JQuery)

  var customer = {
  customer: {
    name: {
      first: 'Joe',
      last: 'Doe'
    },
    email_address: 'joe.doe@example.com'
  }
}
$.ajax({
  url: 'https://app.sprouted.app/api/v1/customers/?public_key=pk_...',
  type: 'POST',
  dataType: 'json',
  contentType: 'application/json',
  data: JSON.stringify(customer)
})

Note: don't forget to set your referrer domain or else your request will be rejected.


Node.js (with Request)

  var request = require("request");

var options = {
  method: 'POST',
  url: 'https://app.sprouted.app/api/v1/customers',
  headers: { authorization: 'Bearer sk_...', 'content-type': 'application/json' },
  body: {
    customer: { name: { first: 'Joe', last: 'Doe' }, email_address: 'joe.doe@example.com' }
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Note: this should be executed server-side in order to safeguard your secret API key.


PHP (with HTTP v2)

  <?php
$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{
  "customer": {
    "name": {
      "first": "Joe",
      "last": "Doe"
    },
    "email_address": "joe.doe@example.com"
  }
}');

$request->setRequestUrl('https://app.sprouted.app/api/v1/customers');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Bearer sk_...',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();
?>

Python (with Requests)

  import requests

url = "https://app.sprouted.app/api/v1/customers"

payload = "{\n  \"customer\": {\n    \"name\": {\n      \"first\": \"Joe\",\n      \"last\": \"Doe\"\n    },\n    \"email_address\": \"joe.doe@example.com\"\n  }\n}"
headers = {
    'authorization': "Bearer sk_...",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Ruby (with Typhoeus)

  require 'typhoeus'
require 'json'

response = Typhoeus.post('https://app.sprouted.app/api/v1/customers',
  body: {
    customer: {
      name: {
        first: 'Joe',
        last: 'Doe'
      },
      email_address: 'joe.doe@example.com'
    }
  }.to_json,
  headers: {
    'authorization': 'Bearer sk_...',
    'content-type': 'application/json'
  })

puts response.success?
puts response.body

Ruby (with Net::HTTP)

  require 'uri'
require 'net/http'
require 'openssl'
require 'json'

url = URI('https://app.sprouted.app/api/v1/customers')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request['authorization'] = 'Bearer sk_...'
request['content-type'] = 'application/json'
body = {
  customer: {
    name: {
      first: 'Joe',
      last: 'Doe'
    },
    email_address: 'joe.doe@example.com'
  }
}
request.body = body.to_json

response = http.request(request)
puts response.read_body

Note: language-specific SDKs are in the works.

© Releasewise B.V. 2020 · Terms of Service · Privacy Policy · Information Security · Feedback · API · Main Site