Onboarding

The following endpoints allows you to get users list from account and map them with POS employeeIds so they can be used during tipping process using employeeId as param to match user and tip received.

v1/talents/list#

Returns a list of users that belongs to account with given credentials. These endpoints can be used with any product.

Request body structure (TS notation)

interface ListTalentsRequest {
  appId: string; // Your app ID
  appSecret: string; // Your app secret
  accountToken: string; // The account token for the business whose payroll run report we want to get
  payload: {
    storeId?: string; // Optional store (location) id
  }
}

Request example

POST /v1/talents/list HTTP/1.1
Host: https://developer.tippy.app
Content-Type: application/json

{
  "appId": "YOUR_APP_ID",
  "appSecret": "YOUR_APP_SECRET",
  "accountToken": "BUSINESS_ACCOUNT_TOKEN",
  "payload": {
      "storeId": "18888"
  }
}

Response body structure (TS notation)

interface ListTalentsResponse {
  data: { // An array of objects, each representing one staff member on a location
    id: string; // Unique identifier for the staff member
    firstName: string;
    lastName: string;
    avatar: string;
    phone: string;
    email: string;
    location: {
      name: string;
      address: string;
    }
  }[]
}

Response example

{
  "data": [
    {
      "id": "32056fcd-a3f1-43d4-8d6f-f5fd5636275b",
      "firstName": "John",
      "lastName": "Doe",
      "avatar": null,
      "phone": "(434) 343-4343",
      "email": "jdoe@example.com",
      "location": {
          "name": "Genesis Boutique",
          "address": "222 FM 527, West Dickinson, TX, 77539"
      }
    },
    {
      "id": "533d7ca0-d3c8-4cb8-ad3f-244964063bef",
      "firstName": "Eva",
      "lastName": "Lewis",
      "avatar": null,
      "phone": "(343) 443-4433",
      "email": "elweis@example.com",
      "location": {
          "name": "Genesis Boutique",
          "address": "222 FM 527, West Dickinson, TX, 77539"
      }
    }
  ]
}

v1/talents/assign#

Assigns provided talent's employeeId with Tippy user identifier.

Request body structure (TS notation)

interface ListTalentsRequest {
  appId: string; // Your app ID
  appSecret: string; // Your app secret
  accountToken: string; // The account token for the business whose payroll run report we want to get
  payload: {
    talents: [ // Array of employees mapping data
      {
        id: string; // User id returned in talents/list endpoint
        employeeId: string; // POS employee id
      }
    ]
  }
}

Request example

{
  "appId": "YOUR_APP_ID",
  "appSecret": "YOUR_APP_SECRET",
  "accountToken": "BUSINESS_ACCOUNT_TOKEN",
  "payload":{
    "talents": [
      {
          "id": "5c37b8ec-a1d4-48f6-b945-2d59a02ec66e",
          "employeeId": "EID10999"
      },
      {
          "id": "3e7b7871-ae5c-455c-977b-e626e58ec034",
          "employeeId": "EID10997"
      },
      {
        "identifier": "666d7ca0-d3c8-4cb8-ad3f-244964063bcc",
        "employeeId": "EID10998",
      }
    ]
  }
}

Response body structure (TS notation)

interface ListTalentsRequest {
  appId: string; // Your app ID
  appSecret: string; // Your app secret
  accountToken: string; // The account token for the business whose payroll run report we want to get
  payload: {
    talents: [ // Array of employees mapping data
      {
        id: string; // User id returned in talents/list endpoint
        employeeId: string; // POS employee id
      }
    ]
  }
}

Response body structure (TS notation)

interface AssignTalentsResponse {
  data: { // An array of objects, each representing one staff member on a location
    mapped: [
      {
        identifier: string;
        employeeId: string;
      }
    ]
    failed: [
      {
        identifier: string;
        employeeId: string;
        error: string;
      }
    ]
  }[]
}

Response example

{
  "data": {
    "mapped": [
      {
        "identifier": "32056fcd-a3f1-43d4-8d6f-f5fd5636275b",
        "employeeId": "EID10999"
      },
      {
        "identifier": "533d7ca0-d3c8-4cb8-ad3f-244964063bef",
        "employeeId": "EID10997"
      }
    ],
    "failed": [
      {
        "identifier": "666d7ca0-d3c8-4cb8-ad3f-244964063bcc",
        "employeeId": "EID10998",
        "error": "Employee already mapped to account with other employee id, please contact Tippy support"
      }
    ]
  }
}