Documentation

1. Introduction

This introduction is meant for developers who want to integrate their startup with our API. If you are just looking for rewards please browse all startups.

Quick links:

Open API 3.0 specification
Swagger 2.0 JSON specification

2. API Endpoint

Overview

There is really one endpoint you have to integrate with. When a user performs an action- your system should POST a new action. The action key can be specified when creating or updating a reward.
https://lucr.io/api/v1/startups/{startup}/users/{user}/actions

Replace {startup} with your startup slug (specified when creating a startup, and visible in your startup's page URL after @ symbol).

Replace {user} with a user's email address. You can optionally replace email address with its md5 hash (lowercase and whitespace-trimmed).

The only required field in the request body is the action parameter with the action name specified when creating a reward.
{
    action: "my-sample-action"
}

Authorization

In your startup edit area you will find API Tokens tab. You should create at least one token and save somewhere in your system (Remember to keep it private).

The API endpoint uses OAuth2 authorization process so you should send the proper authorization header Authorization: Bearer {token}

Example

Given you've created a startup named My startup, which is accessible at https://lucr.io/@my-startup and you've added a reward with the action key named my-sample-action your request should be POST'ed to the URL:

https://lucr.io/api/v1/startups/my-startup/users/user@example.com/actions

with the body:
{
 action: "my-sample-action"
}

Curl example

A simple curl example:
curl -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer TOKEN" \
    -d '{"action":"my-sample-action"}' \
    https://lucr.io/api/v1/startups/my-startup/users/user@example.com/actions

Remember to replace TOKEN with a token you generated.

The 200 status code indicates that everything went smooth.

The 401 status code means there is a problem with your authorization token.

The 404 status code can be caused by wrong startup slug or a user with given email address is not registered to Lucr.io. If you are sure that a startup slug and action name are correct you can safely ignore this error (the user is not registered in our system and cannot be given a reward).

3. Swagger integration

Swagger provides client generation for most of the programming languages. You can import our 2.0 specification in on-line editor from URL: https://lucr.io/api/v1/swagger-2.0.json.

An example integration using Swagger client package in PHP could look like that:

    use Swagger\Client\Api\ActionApi;
    use Swagger\Client\ApiClient;
    use Swagger\Client\Configuration;

    $client = new ApiClient();
    $api = new ActionApi($client);

    $api->addAction(
        'Bearer YOUR-LUCR-API-TOKEN',
        'action-name',
        'my-startup',
        'user@example.com'
    );

4. Notifications

Remember that notifications are totally optional. You can easily create an automated system by placing discount codes directly in the reward's custom message (that goes to the user every time he/she earns a reward).
When a user performs required actions he/she will be awarded with one of your rewards. You will be notified whenever this happens by one or more channels. You can choose from:
  • E-mail notification
  • Slack webhook
  • URL webhook

Webhook notification

If you enabled the URL webhook we will POST to the given URL with a JSON body:

    {
        "action": "action-name",
        "startup": "startup-slug",
        "user": "user@example.com"
    }

You should create a unique and undiscoverable URL or check our server's IP address: 46.101.29.87