Introduction

The Metadata API provides access to the basic resources found within Performio, i.e. Custom Tables, Participants, Periods etc.

Metadata Resources

Batches

Batches are collections of Calculation, Transform and sub-Batch steps that are executed in sequence. A Batch can be provided to a Batch Errand in order to be executed.

GET /metadata/v1/batches

Utilise this endpoint to retrieve all Batches. Results are paginated.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/batches?fromPeriod=1&toPeriod=4&isPublished=true&isDeleteScript=false&page=0&size=20' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Request Parameters
Parameter Description

fromPeriod

(Optional) Number representing the lower Period boundary to filter on.

toPeriod

(Optional) Number representing the upper Period boundary to filter on.

isPublished

(Optional) Boolean representing filtering on published state.

isDeleteScript

(Optional) Boolean representing filtering on whether the Batch is intended to delete data.

page

(Optional) Number representing the page to retrieve. Pages start from 0.

size

(Optional) Number representing the records per page count. Default page size is 20 and the maximum is 2000.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 391

{
  "results" : [ {
    "id" : 1,
    "name" : "Batch 1",
    "fromPeriod" : 1,
    "toPeriod" : 4,
    "isPublished" : true,
    "isDeleteScript" : false
  }, {
    "id" : 2,
    "name" : "Batch 2",
    "fromPeriod" : 1,
    "toPeriod" : 4,
    "isPublished" : true,
    "isDeleteScript" : false
  } ],
  "page" : {
    "totalPages" : 1,
    "totalElements" : 2,
    "hasNext" : false
  }
}
Path Type Description

results

Array

Array of results.

results.[].id

Number

Number representing the ID of the Batch.

results.[].name

String

String representing the name of the Batch.

results.[].fromPeriod

Varies

Number representing the lower Period boundary for when the Batch is active, or Null representing no lower Period boundary.

results.[].toPeriod

Varies

Number representing the upper Period boundary for when the Batch is active, or Null representing no upper Period boundary.

results.[].isPublished

Boolean

Boolean representing the published state of the Batch.

results.[].isDeleteScript

Boolean

Boolean representing the Batch is intended to delete data.

page

Object

Object representing result pagination.

page.totalPages

Number

Number representing the total pages at current page size.

page.totalElements

Number

Number representing the total possible elements for the request.

page.hasNext

Boolean

Boolean representing if there is a next page of results.

GET /metadata/v1/batches/{batchId}

Utilise this endpoint to retrieve a specific Batch.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/batches/1' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Parameter Description

batchId

Number representing the ID of the Batch to fetch.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 126

{
  "id" : 1,
  "name" : "Batch 1",
  "fromPeriod" : 1,
  "toPeriod" : 4,
  "isPublished" : true,
  "isDeleteScript" : false
}
Path Type Description

id

Number

Number representing the ID of the Batch.

name

String

String representing the name of the Batch.

fromPeriod

Varies

Number representing the lower Period boundary for when the Batch is active, or Null representing no lower Period boundary.

toPeriod

Varies

Number representing the upper Period boundary for when the Batch is active, or Null representing no upper Period boundary.

isPublished

Boolean

Boolean representing the published state of the Batch.

isDeleteScript

Boolean

Boolean representing the Batch is intended to delete data.

Error Conditions

Reason

Response

Batch ID provided does not resolve to a Batch.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 161

{
  "timestamp" : 1617843945972,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Batch with ID 1",
  "path" : "/metadata/v1/batches/1"
}

Calculations

Calculations are sets of instructions that are primarily responsible for calculating commissions within Performio.

Calculations come in three main types: Plan Template, Leader Board and Script.

  • Plan Template calculations are configured within the system and are made up of one to many individual components.

  • Leader Board calculations specifically for calculating Leader Board standings.

  • Script calculations are and advanced feature wrapping scripts written in Python that work outside the bounds of what is available through standard components.

A Calculation, either on its own or part of a Batch, can be provided to a Calculation Errand in order to be executed.

GET /metadata/v1/calculations/plan-templates

Utilise this endpoint to retrieve all Plan Template Calculations. Results are paginated.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/calculations/plan-templates?fromPeriod=1&toPeriod=4&isPublished=true&page=0&size=20' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Request Parameters
Parameter Description

fromPeriod

(Optional) Number representing the lower Period boundary to filter on.

toPeriod

(Optional) Number representing the upper Period boundary to filter on.

isPublished

(Optional) Boolean representing filtering on published state.

page

(Optional) Number representing the page to retrieve. Pages start from 0.

size

(Optional) Number representing the records per page count. Default page size is 20 and the maximum is 2000.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 403

{
  "results" : [ {
    "id" : 1,
    "name" : "Calculation 1",
    "type" : "sip-component",
    "fromPeriod" : 1,
    "toPeriod" : 4,
    "isPublished" : true
  }, {
    "id" : 2,
    "name" : "Calculation 2",
    "type" : "sip-component",
    "fromPeriod" : 1,
    "toPeriod" : 4,
    "isPublished" : true
  } ],
  "page" : {
    "totalPages" : 1,
    "totalElements" : 2,
    "hasNext" : false
  }
}
Path Type Description

results

Array

Array of results.

results.[].id

Number

Number representing the ID of the Calculation.

results.[].name

String

String representing the name of the Calculation.

results.[].type

String

String representing the type of the Calculation.

results.[].fromPeriod

Varies

Number representing the lower Period boundary for when the Calculation is active, or Null representing no lower Period boundary.

results.[].toPeriod

Varies

Number representing the upper Period boundary for when the Calculation is active, or Null representing no upper Period boundary.

results.[].isPublished

Boolean

Boolean representing the published state of the Calculation.

page

Object

Object representing result pagination.

page.totalPages

Number

Number representing the total pages at current page size.

page.totalElements

Number

Number representing the total possible elements for the request.

page.hasNext

Boolean

Boolean representing if there is a next page of results.

GET /metadata/v1/calculations/plan-templates/{calculationId}

Utilise this endpoint to retrieve a specific Plan Template Calculation.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/calculations/plan-templates/1' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Parameter Description

calculationId

Number representing the ID of the Calculation to fetch.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 132

{
  "id" : 1,
  "name" : "Calculation 1",
  "type" : "sip-component",
  "fromPeriod" : 1,
  "toPeriod" : 4,
  "isPublished" : true
}
Path Type Description

id

Number

Number representing the ID of the Calculation.

name

String

String representing the name of the Calculation.

type

String

String representing the type of the Calculation.

fromPeriod

Varies

Number representing the lower Period boundary for when the Calculation is active, or Null representing no lower Period boundary.

toPeriod

Varies

Number representing the upper Period boundary for when the Calculation is active, or Null representing no upper Period boundary.

isPublished

Boolean

Boolean representing the published state of the Calculation.

Error Conditions

Reason

Response

Calculation ID provided does not resolve to a Plan Template Calculation.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 201

{
  "timestamp" : 1617843945220,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Plan Template Calculation with ID 1",
  "path" : "/metadata/v1/calculations/plan-templates/1"
}

GET /metadata/v1/calculations/leader-boards

Utilise this endpoint to retrieve all Leader Board Calculations. Results are paginated.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/calculations/leader-boards?fromPeriod=1&toPeriod=4&isPublished=true&page=0&size=20' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Request Parameters
Parameter Description

fromPeriod

(Optional) Number representing the lower Period boundary to filter on.

toPeriod

(Optional) Number representing the upper Period boundary to filter on.

isPublished

(Optional) Boolean representing filtering on published state.

page

(Optional) Number representing the page to retrieve. Pages start from 0.

size

(Optional) Number representing the records per page count. Default page size is 20 and the maximum is 2000.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 403

{
  "results" : [ {
    "id" : 1,
    "name" : "Calculation 1",
    "type" : "league-ladder",
    "fromPeriod" : 1,
    "toPeriod" : 4,
    "isPublished" : true
  }, {
    "id" : 2,
    "name" : "Calculation 2",
    "type" : "league-ladder",
    "fromPeriod" : 1,
    "toPeriod" : 4,
    "isPublished" : true
  } ],
  "page" : {
    "totalPages" : 1,
    "totalElements" : 2,
    "hasNext" : false
  }
}
Path Type Description

results

Array

Array of results.

results.[].id

Number

Number representing the ID of the Calculation.

results.[].name

String

String representing the name of the Calculation.

results.[].type

String

String representing the type of the Calculation.

results.[].fromPeriod

Varies

Number representing the lower Period boundary for when the Calculation is active, or Null representing no lower Period boundary.

results.[].toPeriod

Varies

Number representing the upper Period boundary for when the Calculation is active, or Null representing no upper Period boundary.

results.[].isPublished

Boolean

Boolean representing the published state of the Calculation.

page

Object

Object representing result pagination.

page.totalPages

Number

Number representing the total pages at current page size.

page.totalElements

Number

Number representing the total possible elements for the request.

page.hasNext

Boolean

Boolean representing if there is a next page of results.

GET /metadata/v1/calculations/leader-boards/{calculationId}

Utilise this endpoint to retrieve a specific Leader Board Calculation.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/calculations/leader-boards/1' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Parameter Description

calculationId

Number representing the ID of the Calculation to fetch.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 132

{
  "id" : 1,
  "name" : "Calculation 1",
  "type" : "league-ladder",
  "fromPeriod" : 1,
  "toPeriod" : 4,
  "isPublished" : true
}
Path Type Description

id

Number

Number representing the ID of the Calculation.

name

String

String representing the name of the Calculation.

type

String

String representing the type of the Calculation.

fromPeriod

Varies

Number representing the lower Period boundary for when the Calculation is active, or Null representing no lower Period boundary.

toPeriod

Varies

Number representing the upper Period boundary for when the Calculation is active, or Null representing no upper Period boundary.

isPublished

Boolean

Boolean representing the published state of the Calculation.

Error Conditions

Reason

Response

Calculation ID provided does not resolve to a Leader Board Calculation.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 199

{
  "timestamp" : 1617843944926,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Leader Board Calculation with ID 1",
  "path" : "/metadata/v1/calculations/leader-boards/1"
}

GET /metadata/v1/calculations/scripts

Utilise this endpoint to retrieve all Script Calculations. Results are paginated.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/calculations/scripts?fromPeriod=1&toPeriod=4&isPublished=true&page=0&size=20' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Request Parameters
Parameter Description

fromPeriod

(Optional) Number representing the lower Period boundary to filter on.

toPeriod

(Optional) Number representing the upper Period boundary to filter on.

isPublished

(Optional) Boolean representing filtering on published state.

page

(Optional) Number representing the page to retrieve. Pages start from 0.

size

(Optional) Number representing the records per page count. Default page size is 20 and the maximum is 2000.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 389

{
  "results" : [ {
    "id" : 1,
    "name" : "Calculation 1",
    "type" : "script",
    "fromPeriod" : 1,
    "toPeriod" : 4,
    "isPublished" : true
  }, {
    "id" : 2,
    "name" : "Calculation 2",
    "type" : "script",
    "fromPeriod" : 1,
    "toPeriod" : 4,
    "isPublished" : true
  } ],
  "page" : {
    "totalPages" : 1,
    "totalElements" : 2,
    "hasNext" : false
  }
}
Path Type Description

results

Array

Array of results.

results.[].id

Number

Number representing the ID of the Calculation.

results.[].name

String

String representing the name of the Calculation.

results.[].type

String

String representing the type of the Calculation.

results.[].fromPeriod

Varies

Number representing the lower Period boundary for when the Calculation is active, or Null representing no lower Period boundary.

results.[].toPeriod

Varies

Number representing the upper Period boundary for when the Calculation is active, or Null representing no upper Period boundary.

results.[].isPublished

Boolean

Boolean representing the published state of the Calculation.

page

Object

Object representing result pagination.

page.totalPages

Number

Number representing the total pages at current page size.

page.totalElements

Number

Number representing the total possible elements for the request.

page.hasNext

Boolean

Boolean representing if there is a next page of results.

GET /metadata/v1/calculations/scripts/{calculationId}

Utilise this endpoint to retrieve a specific Script Calculation.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/calculations/scripts/1' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Parameter Description

calculationId

Number representing the ID of the Calculation to fetch.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 125

{
  "id" : 1,
  "name" : "Calculation 1",
  "type" : "script",
  "fromPeriod" : 1,
  "toPeriod" : 4,
  "isPublished" : true
}
Path Type Description

id

Number

Number representing the ID of the Calculation.

name

String

String representing the name of the Calculation.

type

String

String representing the type of the Calculation.

fromPeriod

Varies

Number representing the lower Period boundary for when the Calculation is active, or Null representing no lower Period boundary.

toPeriod

Varies

Number representing the upper Period boundary for when the Calculation is active, or Null representing no upper Period boundary.

isPublished

Boolean

Boolean representing the published state of the Calculation.

Error Conditions

Reason

Response

Calculation ID provided does not resolve to a Script Calculation.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 187

{
  "timestamp" : 1617843945270,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Script Calculation with ID 1",
  "path" : "/metadata/v1/calculations/scripts/1"
}

Custom Tables

Custom Tables are system or user generated tables within Performio used to stage, transform and store data. You can import data into Custom Tables by utilising Import Errands, and you can extract data from Custom Tables by utilising the Extract Custom Table API.

GET /metadata/v1/custom-tables

Utilise this endpoint to retrieve all Custom Tables, including all Custom Table Fields. Results are paginated.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/custom-tables?page=0&size=20' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Request Parameters
Parameter Description

page

(Optional) Number representing the page to retrieve. Pages start from 0.

size

(Optional) Number representing the records per page count. Default page size is 20 and the maximum is 2000.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 530

{
  "results" : [ {
    "name" : "Custom Table",
    "description" : "Custom table for test cases.",
    "fields" : [ {
      "name" : "Custom Table Field 1",
      "size" : 255,
      "type" : "STRING",
      "databaseName" : "custom_table_field_1"
    }, {
      "name" : "Custom Table Field 2",
      "size" : 0,
      "type" : "INTEGER",
      "databaseName" : "custom_table_field_2"
    } ],
    "databaseName" : "ct_custom_table"
  } ],
  "page" : {
    "totalPages" : 1,
    "totalElements" : 1,
    "hasNext" : false
  }
}
Path Type Description

results

Array

Array of results.

results.[].databaseName

String

String representing the Custom Table’s database table name.

results.[].name

String

String representing the Custom Table’s name.

results.[].description

String

String representing the Custom Table’s description.

results.[].fields

Array

Array of Custom Table Fields associated with the Custom Table.

results.[].fields.[].databaseName

String

String representing the Custom Table Field’s database column name.

results.[].fields.[].name

String

String representing the Custom Table Field’s name.

results.[].fields.[].size

Number

Number representing the total allowable size of the Custom Table Field. Size is 0 on all types except String.

results.[].fields.[].type

String

String representing the Custom Table Field’s data type. May be one of the following: Primary Key (pk), String (string), Number (int), Decimal (decimal), Date (date)

page

Object

Object representing result pagination.

page.totalPages

Number

Number representing the total pages at current page size.

page.totalElements

Number

Number representing the total possible elements for the request.

page.hasNext

Boolean

Boolean representing if there is a next page of results.

GET /metadata/v1/custom-tables/{customTableDatabaseName}

Utilise this endpoint to retrieve a specific Custom Table, including a list of Custom Table Fields.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/custom-tables/ct_custom_table' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Parameter Description

customTableDatabaseName

String representing the database name of Custom Table to fetch.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 391

{
  "name" : "Custom Table",
  "description" : "Custom table for test cases.",
  "fields" : [ {
    "name" : "Custom Table Field 1",
    "size" : 255,
    "type" : "STRING",
    "databaseName" : "custom_table_field_1"
  }, {
    "name" : "Custom Table Field 2",
    "size" : 0,
    "type" : "INTEGER",
    "databaseName" : "custom_table_field_2"
  } ],
  "databaseName" : "ct_custom_table"
}
Path Type Description

databaseName

String

String representing the Custom Table’s database table name.

name

String

String representing the Custom Table’s name.

description

String

String representing the Custom Table’s description.

fields

Array

Array of Custom Table Fields associated with the Custom Table.

fields.[].databaseName

String

String representing the Custom Table Field’s database column name.

fields.[].name

String

String representing the Custom Table Field’s name.

fields.[].size

Number

Number representing the total allowable size of the Custom Table Field. Size is 0 on all types except String.

fields.[].type

String

String representing the Custom Table Field’s data type. May be one of the following: Primary Key (pk), String (string), Number (int), Decimal (decimal), Date (date)

Error Conditions

Reason

Response

Custom Table Database Name provided does not resolve to a Custom Table.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 213

{
  "timestamp" : 1617843946491,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Custom Table with database name ct_custom_table",
  "path" : "/metadata/v1/custom-tables/ct_custom_table"
}

Import File Types

Import File Types describe the structure of Standard and Custom importers in the system. They provide a description of how to organise your data if you intend to import file or record based data via an Import Errand.

GET /metadata/v1/import-file-types/standard

Utilise this endpoint to retrieve all Standard Import File Types. Standard Import File Types are generated by the system and provide a mechanism for importing file or record data into both system generated Custom Tables and for specialised entities such as Participants. Results are paginated.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/import-file-types/standard?page=0&size=20' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Request Parameters
Parameter Description

page

(Optional) Number representing the page to retrieve. Pages start from 0.

size

(Optional) Number representing the records per page count. Default page size is 20 and the maximum is 2000.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 672

{
  "results" : [ {
    "id" : "standard-1",
    "name" : "Account",
    "description" : "Link the master customer number to the participant",
    "catalogue" : "Standard Import Type",
    "recordFormat" : "{\"Master Customer Number(compulsory, text)\":\"<>\",\"Name(compulsory, text)\":\"<>\",\"Source(compulsory, text)\":\"<>\"}"
  }, {
    "id" : "standard-2",
    "name" : "Market",
    "description" : "Upload the market details",
    "catalogue" : "Standard Import Type",
    "recordFormat" : "{\"Name (compulsory, text)\":\"<>\",\"Market Id (compulsory, text)\":\"<>\"}"
  } ],
  "page" : {
    "totalPages" : 1,
    "totalElements" : 2,
    "hasNext" : false
  }
}
Path Type Description

results

Array

Array of results.

results.[].id

String

String representing the ID of the Import File Type. Utilised when creating an Import Errand to indicate which Import File Type to import data for.

results.[].name

String

String representing the name of the Import File Type.

results.[].description

String

String representing the description of the Import File Type.

results.[].catalogue

String

String representing the creation method of the Import File Type. Standard indicates it is system generated, custom indicates it is user generated.

results.[].recordFormat

String

String representing the JSON representation of a row for the Import File Type.

page

Object

Object representing result pagination.

page.totalPages

Number

Number representing the total pages at current page size.

page.totalElements

Number

Number representing the total possible elements for the request.

page.hasNext

Boolean

Boolean representing if there is a next page of results.

GET /metadata/v1/import-file-types/custom

Utilise this endpoint to retrieve all Custom Import File Types. Custom Import File Types are created by users and provide a mechanism to import file or record data into Custom Tables. Results are paginated.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/import-file-types/custom?page=0&size=20' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Request Parameters
Parameter Description

page

(Optional) Number representing the page to retrieve. Pages start from 0.

size

(Optional) Number representing the records per page count. Default page size is 20 and the maximum is 2000.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 443

{
  "results" : [ {
    "id" : "1",
    "name" : "Sales Commission Table import",
    "type" : "adhoc",
    "description" : "Description",
    "catalogue" : "",
    "recordFormat" : "{}"
  }, {
    "id" : "2",
    "name" : "Sales Data import",
    "type" : "adhoc",
    "description" : "Description",
    "catalogue" : "",
    "recordFormat" : "{}"
  } ],
  "page" : {
    "totalPages" : 1,
    "totalElements" : 2,
    "hasNext" : false
  }
}
Path Type Description

results

Array

Array of results.

results.[].id

String

String representing the ID of the Import File Type. Utilised when creating an Import Errand to indicate which Import File Type to import data for.

results.[].name

String

String representing the name of the Import File Type.

results.[].description

String

String representing the description of the Import File Type.

results.[].catalogue

String

String representing the creation method of the Import File Type. Standard indicates it is system generated, custom indicates it is user generated.

results.[].recordFormat

String

String representing the JSON representation of a row for the Import File Type.

results.[].type

String

String representing the purpose of the importer. May be Adhoc (adhoc), Analytics Main (analytics_main), Hard Coded (hard-coded), Salesforce Opportunity Data Import (opportunity), Participant Source Data (participant_source_data), Salesforce Object Import (salesforce_object) or Scripted (script-based).

page

Object

Object representing result pagination.

page.totalPages

Number

Number representing the total pages at current page size.

page.totalElements

Number

Number representing the total possible elements for the request.

page.hasNext

Boolean

Boolean representing if there is a next page of results.

Participants

Participants are the end users of Performio. They may be provided to Batch and Calculation Errands to constrain the resulting action to within boundaries.

GET /metadata/v1/participants

Utilise this endpoint to retrieve all Participants. Results are paginated.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/participants?isEnabled=true&page=0&size=20' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Request Parameters
Parameter Description

isEnabled

(Optional) Boolean representing filtering on enabled state.

page

(Optional) Number representing the page to retrieve. Pages start from 0.

size

(Optional) Number representing the records per page count. Default page size is 20 and the maximum is 2000.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 410

{
  "results" : [ {
    "id" : 1,
    "eid" : "participant1",
    "firstName" : "Participant",
    "surname" : "One",
    "isActive" : true,
    "isEnabled" : true
  }, {
    "id" : 2,
    "eid" : "participant2",
    "firstName" : "Participant",
    "surname" : "Two",
    "isActive" : false,
    "isEnabled" : true
  } ],
  "page" : {
    "totalPages" : 1,
    "totalElements" : 2,
    "hasNext" : false
  }
}
Path Type Description

results

Array

Array of results.

results.[].id

Number

Number representing the ID of the Participant.

results.[].eid

String

String representing the EID of the Participant.

results.[].firstName

String

String representing the first name of the Participant.

results.[].surname

String

String representing the surname of the Participant.

results.[].isActive

Boolean

Boolean representing the active state of the Participant.

results.[].isEnabled

Boolean

Boolean representing the enabled state of the Participant.

page

Object

Object representing result pagination.

page.totalPages

Number

Number representing the total pages at current page size.

page.totalElements

Number

Number representing the total possible elements for the request.

page.hasNext

Boolean

Boolean representing if there is a next page of results.

GET /metadata/v1/participants/{participantId}

Utilise this endpoint to retrieve a specific Participant.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/participants/1' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Parameter Description

participantId

Number representing the ID of the Participant to fetch.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 135

{
  "id" : 1,
  "eid" : "participant1",
  "firstName" : "Participant",
  "surname" : "One",
  "isActive" : true,
  "isEnabled" : true
}
Path Type Description

id

Number

Number representing the ID of the Participant.

eid

String

String representing the EID of the Participant.

firstName

String

String representing the first name of the Participant.

surname

String

String representing the surname of the Participant.

isActive

Boolean

Boolean representing the active state of the Participant.

isEnabled

Boolean

Boolean representing the enabled state of the Participant.

Error Conditions

Reason

Response

Participant ID provided does not resolve to a Participant.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 172

{
  "timestamp" : 1617843944430,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Participant with ID 1",
  "path" : "/metadata/v1/participants/1"
}

Periods

Periods are the base time division unit within Performio. Each Period encompasses a month, starting from the configured Period initial date, and are sequentially numbered until the final configured Period. They may be provided to Batch, Calculation and Import Errands to constrain the resulting action to within boundaries.

GET /metadata/v1/periods

Utilise this endpoint to retrieve all Periods. Results are paginated.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/periods?page=0&size=20' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Request Parameters
Parameter Description

page

(Optional) Number representing the page to retrieve. Pages start from 0.

size

(Optional) Number representing the records per page count. Default page size is 20 and the maximum is 2000.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 644

{
  "results" : [ {
    "periodNumber" : 1,
    "isLocked" : false,
    "status" : {
      "name" : "Period One Status",
      "description" : "Period One Status Description",
      "visibilityRegex" : "*.all",
      "approvalStatus" : true
    },
    "customLabel" : "Period One"
  }, {
    "periodNumber" : 2,
    "isLocked" : false,
    "status" : {
      "name" : "Period Two Status",
      "description" : "Period Two Status Description",
      "visibilityRegex" : "*.all",
      "approvalStatus" : false
    },
    "customLabel" : "Period Two"
  } ],
  "page" : {
    "totalPages" : 1,
    "totalElements" : 2,
    "hasNext" : false
  }
}
Path Type Description

results

Array

Array of results.

results.[].periodNumber

Number

Number representing the assigned number of the Period.

results.[].customLabel

String

String representing the custom label given to the Period.

results.[].isLocked

Boolean

Boolean representing the locked state of the Period.

results.[].status

Object

Object representing the assigned status of the Period.

results.[].status.name

String

String representing the name of the assigned status of the Period.

results.[].status.description

String

String representing the description of the assigned status of the Period.

results.[].status.visibilityRegex

String

String representing the visibility regex of the assigned status of the Period.

results.[].status.approvalStatus

Boolean

String representing the approval state of the assigned status of the Period.

page

Object

Object representing result pagination.

page.totalPages

Number

Number representing the total pages at current page size.

page.totalElements

Number

Number representing the total possible elements for the request.

page.hasNext

Boolean

Boolean representing if there is a next page of results.

GET /metadata/v1/periods/{periodNumber}

Utilise this endpoint to retrieve a specific Period.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/metadata/v1/periods/1' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Parameter Description

periodNumber

Number representing the number assigned to the Period to fetch.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 246

{
  "periodNumber" : 1,
  "isLocked" : false,
  "status" : {
    "name" : "Period One Status",
    "description" : "Period One Status Description",
    "visibilityRegex" : "*.all",
    "approvalStatus" : true
  },
  "customLabel" : "Period One"
}
Path Type Description

periodNumber

Number

Number representing the assigned number of the Period.

customLabel

String

String representing the custom label given to the Period.

isLocked

Boolean

Boolean representing the locked state of the Period.

status

Object

Object representing the assigned status of the Period.

status.name

String

String representing the name of the assigned status of the Period.

status.description

String

String representing the description of the assigned status of the Period.

status.visibilityRegex

String

String representing the visibility regex of the assigned status of the Period.

status.approvalStatus

Boolean

String representing the approval state of the assigned status of the Period.

Error Conditions

Reason

Response

Period Number provided does not resolve to a Period.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 166

{
  "timestamp" : 1617843944670,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Period with number 1",
  "path" : "/metadata/v1/periods/1"
}