API

Welcome to Alpharank!

Alpharank is a data modeling company that helps you find the most important customers. You provide us with a file that contains purchase data, we process it and then return it with your results. It's that simple. Begin with creating a user account and then initiating a campaign.

For any questions or comments feel free to contact us.

User Account

The users endpoint allows you to create an account, login with your username and password. You can also retrieve information about your user account.

Create a New User

To be able to create a new user, you will have to make a POST request to the users endpoint. This endpoint expects a JSON body where you have to include the email and username. When a user is created, it does not set the password on the request. The API sends an email to the user for him to set up a password.

Sample Request: post https://alpharank.io/api/v1/users

User Login

Login

On a successfull login, the API returns an "auth token". This token is the one required on further requests to identify the user. It is valid for one hour. After that, you have to login again for a new token. If you are using our Python SDK, this is done automatically.

Sample Request: post https://alpharank.io/api/v1/users/login
View Sample Response
{
  "auth_token": "4c28deddabb740f4bce3f1e47fdb1f46"
}

User

User Details

You can get your own user details by making a request to the special endpoint me

Sample Request: get https://alpharank.io/api/v1/users/me
HEADERS Content-Type: application/json x-auth-token: your-auth-token
View Sample Response
{
  "user_id": 42,
  "email": "developer@example.com",
  "username": "developer"
}

Files Collection

Here are the different options when dealing with data files.

List Files Uploaded

Retrieve a list of the files uploaded by the user

Sample Request: get https://alpharank.io/api/v1/uploads
HEADERS Content-Type: application/json x-auth-token: your-auth-token
View Sample Response
{
  "data": [
    {
      "id": 1,
      "name": "data.csv",
      "records": 23466634,
      "campaigns": [
        {
          "id": 0,
          "name": ""
        }
      ],
      "_links": [
        {
          "rel": "self",
          "href": "/uploads/1",
          "method": "GET"
        }
      ]
    }
  ]
}

Upload a New File

Uploads a file to the API. Please, read the Data File Guide for information on what information it should contain.

Sample Request: post https://alpharank.io/api/v1/uploads
HEADERS Content-Type: multipart/form-data; boundary=---BOUNDARY x-auth-token: your-auth-token
View Sample Response
{
  "id": 1,
  "name": "data.csv",
  "records": 23466634,
  "campaigns": [
    {
      "id": 0,
      "name": ""
    }
  ],
  "_links": [
    {
      "rel": "self",
      "href": "/uploads/1",
      "method": "GET"
    }
  ]
}

File Tasks

File Details

Get the details of a file.

Sample Request: get https://alpharank.io/api/v1/uploads/file_id
HEADERS Content-Type: application/json x-auth-token: your-auth-token
View Sample Response
{
  "id": 1,
  "name": "data.csv",
  "records": 23466634,
  "campaigns": [
    {
      "id": 0,
      "name": ""
    }
  ],
  "_links": [
    {
      "rel": "self",
      "href": "/uploads/1",
      "method": "GET"
    }
  ]
}

Delete a File

Deletes a file from the database and any association that it had with any campaign.

Sample Request: delete https://api.alpharank.io/v1/uploads/file_id
HEADERS Content-Type: application/json x-auth-token: your-auth-token

Campaigns Collection

List All Campaigns

Get a list of all Campaigns that you have created. You can filter campaigns by status or sort them out by some attributes.

Sample Request: get https://api.alpharank.io/v1/campaigns?status=WAITING&sort_by=id
HEADERS Content-Type: application/json x-auth-token: your-auth-token
View Sample Response
{
  "data": [
    {
      "campaign_id": 0,
      "campaign_name": "Data Import",
      "status": "",
      "start_time": 0,
      "end_time": 0,
      "completion_time": 0,
      "influencers": [
        {
          "influencer_id": "",
          "influencees": []
        }
      ],
      "files": [
        {
          "file_id": "1",
          "file_name": "data.csv"
        }
      ],
      "created_at": 1462886879,
      "updated_at": 1462886879,
      "_links": [
        {
          "rel": "self",
          "href": "/uploads/1",
          "method": "GET"
        }
      ]
    }
  ]
}

Create a New Campaign

Sample Request: post https://api.alpharank.io/v1/campaigns?status=WAITING&sort_by=id
HEADERS Content-Type: application/json x-auth-token: your-auth-token
View Sample Response
{
  "campaign_id": 0,
  "campaign_name": "Data Import",
  "status": "",
  "start_time": 0,
  "end_time": 0,
  "completion_time": 0,
  "influencers": [
    {
      "influencer_id": "",
      "influencees": []
    }
  ],
  "files": [
    {
      "file_id": "1",
      "file_name": "data.csv"
    }
  ],
  "created_at": 1462886879,
  "updated_at": 1462886879,
  "_links": [
    {
      "rel": "self",
      "href": "/uploads/1",
      "method": "GET"
    }
  ]
}

Campaign

Details

Sample Request: get https://alpharank.io/api/v1/campaigns/campaign_id
HEADERS Content-Type: application/json x-auth-token: your-auth-token
View Sample Response
{
  "campaign_id": 0,
  "campaign_name": "Data Import",
  "status": "",
  "start_time": 0,
  "end_time": 0,
  "completion_time": 0,
  "influencers": [
    {
      "influencer_id": "",
      "influencees": []
    }
  ],
  "files": [
    {
      "file_id": "1",
      "file_name": "data.csv"
    }
  ],
  "created_at": 1462886879,
  "updated_at": 1462886879,
  "_links": [
    {
      "rel": "self",
      "href": "/uploads/1",
      "method": "GET"
    }
  ]
}

Update

You can update a campaign only if it's status is "NOT_RUN". For more information, please, check the Campaign Guide.

Sample Request: put https://alpharank.io/api/v1/campaigns/campaign_id
HEADERS Content-Type: application/json
View Sample Response
{
  "campaign_id": 0,
  "campaign_name": "Data Import 2",
  "status": "",
  "start_time": 0,
  "end_time": 0,
  "completion_time": 0,
  "influencers": [
    {
      "influencer_id": "",
      "influencees": []
    }
  ],
  "files": [
    {
      "file_id": "2",
      "file_name": "data2.csv"
    }
  ],
  "created_at": 1462886879,
  "updated_at": 1462886890,
  "_links": [
    {
      "rel": "self",
      "href": "/uploads/1",
      "method": "GET"
    }
  ]
}

Delete

Deletes a campaign but the files associated with it remains intact.

Sample Request: delete https://alpharank.io/api/v1/campaigns/campaign_id
HEADERS Content-Type: application/json x-auth-token: your-auth-token

Campaign Executions

Execute a Campaign

Changes the campaign status to "WAITING" and no changes can be made to the campaign

Sample Request: post https://alpharank.io/api/v1/campaigns/campaign_id/execute
HEADERS Content-Type: application/json x-auth-token: your-auth-token
View Sample Response
{
  "campaign_id": 0,
  "campaign_name": "Data Import 2",
  "status": "",
  "start_time": 0,
  "end_time": 0,
  "completion_time": 0,
  "influencers": [
    {
      "influencer_id": "",
      "influencees": []
    }
  ],
  "files": [
    {
      "file_id": "2",
      "file_name": "data2.csv"
    }
  ],
  "created_at": 1462886879,
  "updated_at": 1462886890,
  "_links": [
    {
      "rel": "self",
      "href": "/uploads/1",
      "method": "GET"
    }
  ]
}

Cancel an execution

Cancel the execution of a campaign. It's new status will be "NOT_RUN"

Sample Request: delete https://api.alpharank.io/v1/campaigns/campaign_id/execute
HEADERS Content-Type: application/json x-auth-token: your-auth-token

Files on Campaign

Details

Retrieves all the files associated with the campaign.

Sample Request: get https://api.alpharank.io/v1/campaigns/campaign_id/files
HEADERS Content-Type: application/json x-auth-token: your-auth-token
View Sample Response
{
  "data": [
    {
      "id": 1,
      "name": "data.csv",
      "records": 23466634,
      "campaigns": [
        {
          "id": 1,
          "name": "Data Import"
        }
      ],
      "_links": [
        {
          "rel": "self",
          "href": "/uploads/1",
          "method": "GET"
        }
      ]
    }
  ]
}

File on Campaign

Unlink File

This request unlink a file from a campaign. It doesn't delete the file.

Sample Request: delete https://alpharank.io/api/v1/campaigns/campaign_id/files/file_id
HEADERS Content-Type: application/json x-auth-token: your-auth-token

Our Office

Silicon Valley

25 Taylor St
San Francisco, CA 94102

Contact Us

Ready to analyze your customer network?