NAV Navbar
Solar Staff

Overview

The Solar Staff API serves to integrate Solar Staff into your project. This API documentation gives developers a detailed description of all the available requests.

General Information

The Solar Staff API includes methods for working with tasks and freelancers. After registering as your company's administrator, you can invite and create freelancers, manage tasks, and initiate withdrawals to freelancers' payment methods.

Quickstart presents the most popular use case for the API.

The API is based on a set of HTTP methods that are used to make requests and receive responses for each operation. All responses are returned in JSON format. You can use any tools and languages to work with the API. In this guide, we use PHP to show the workings of the API.

Solar Staff provides developers with a convenient sandbox to test things out before deploying to production. To make use of the sandbox, contact the Solar Staff sales department.

Base URL

The current API version is v2. All URLs to API endpoints in this documentation include the following base URL: https://my.solar-staff.com/api/

In the header of every request, you need to pass Accept: application/json.

Authentication and Authorization

Authentication is performed using JSON Web Tokens (JWTs). After receiving a JWT, you need to pass it in the request header: Authorization: Bearer TOKEN_HERE.

If you have several companies, you can pass the x-company-id parameter in the request header. In this case, you can simultaneously make requests for all the companies without updating the token, instead just passing a company ID in each request.

The authentication process looks as follows:

Authentication

JWT Request

Request

HTTP Request
Request body
Parameter Name Type Required Description
username string Yes Username
password string Yes Password
code string No Two-factor authentication (2FA) code. Depending on the user's account settings:
  • If 2FA is enabled, this parameter is required to obtain a token. If not passed, an SMS will be sent. Once the code is received, you need to call this request again.
  • If 2FA is not enabled, this parameter is not required.

Response

Property Name Type Description
token string JWT token
refreshToken string JWT token used for token update

JWT Update

Request

HTTP Request
Request body
Parameter Name Type Required Description
refreshToken string Yes JWT token

Response

Property Name Type Description
token string JWT
refreshToken string JWT used for token update

API Response

All responses from the API are formatted as JSON.

Error Codes and Their Descriptions

Below are all the possible response status codes.

HTTP Code Type Description
200 Success The request succeeded
401 Error: Unauthorized Invalid authentication data
403 Forbidden Access denied, authorization error
422 Validation Error Request can't be processed due to a validation error. Details of the error are provided in the response payload as `{fieldName: errorText}`.
409 Error While Executing Request Error during request execution. Details are provided in the response payload as `{"error description"}`.

Quickstart

The quickstart guide serves as an introduction to the Solar Staff API and contains instructions for the most common actions in the system:

Quickstart

Before You Begin

Authentication and Authorization

Authentication is performed using JSON Web Tokens (JWTs). After receiving a JWT, you need to pass it in the request header: Authorization: Bearer TOKEN_HERE.

To have a JWT generated, you need to send a JWT request where you pass the username, password, and, if necessary, a 2FA code.

The request's method and URI: POST https://my.solar-staff.com/api/login

The JWT you receive needs to be passed in the header of all further requests.

To learn more, see Authentication and Authorization.

API Use Cases

The main scenarios of using the API depend on the way you interact with freelancers:

  • Your contractors can sign up for Solar Staff and perform basic operations there.
  • Your contractors are not going to create Solar Staff accounts, and you will send payments to them yourself.

If your freelancers are going to sign up for and use Solar Staff, the recommended steps are as follows:

Use_case_1

  1. Find or invite a freelancer. The freelancer will receive an invite email with a sign-up link. To check the sign-up status, do a freelancer search request with a filter by email: users who have completed and confirmed their registration will have the isRegistered parameter as "true". Next, the freelancer needs to get verified.
  2. Create a new task.
  3. The freelancer confirms and completes the task.
  4. Accept the task.
  5. Pay for the task. The payment amount is debited from the client's balance and credited to the freelancer's balance.

If your freelancers are not going to use Solar Staff independently (change task statuses, add payment methods, or withdraw task payment), then the recommended steps are as follows:

Use_case_1

  1. Find or invite a freelancer. The freelancer will need to fill in their details and confirm the registration in the service by following an email link.
  2. Create a new task.
  3. Change task statuses in sequence: "Accepted by freelancer", "Completed".
  4. Accept the task.
  5. Pay for the task
  6. Retrieve a freelancer's payment method or add a new one. Only a freelancer can add a new payment method. To add a payment method, you need to send a confirmation code to the freelancer and then generate a link to the screen where the freelancer can input the payment details.
  7. Create a payout to a freelancer's payment method for a task that's been paid.

Inviting Freelancers

To add a freelancer to your team, call the invite freelancer request.

The request's method and URI: POST https://my.solarstaff.com/api/customer/freelancers

A successful request returns an empty response with code 200.

Creating Tasks

To create a task, use this request, passing all the required task parameters: category, attributes, name, description, and price.

The request's method and URI: POST https://my.solarstaff.com/api/tasks

A successful request returns an empty response with code 200.

Changing Task Statuses

The stages of a task are as follows:

  • Create a task
  • Start the task
  • Complete the task
  • Accept/reject task results
  • Pay for the task

When using the API, you need to have these stages performed sequentially. Paying for a task is done via a [separate request](#e010741392) (payment is only made to a freelancer's balance). All other status transitions are handled using the change task status request. In other words, when making a request, you need to observe the sequence with the following statuses:

  • Start task (`ID=2`)
  • Complete task (`ID=3`)
  • Accept task results (`ID=4`)

The request's method and URI: PUT https://my.solar-staff.com/api/customer/tasks/{taskId||uuid}

A successful request returns an empty response with code 200.

Task Payment

To pay for a task, you only need to provide a task ID in this request.

The request's method and URI: POST https://my.solar-staff.com/api/customer/tasks/pay

A successful request returns an empty response with code 200.

Tasks

The API includes a number of requests for task management.

Task Statuses

These are task statuses available in Solar Staff (the diagram features only the main ones, see the complete list of statuses in the table below):

Task statuses

Status ID Description Initiated by
`Unconfirmed` `ID=1` Task has been created Client
`In progress` `ID=2` Freelancer started the task Freelancer
`Client review` `ID=3` Freelancer has completed the task and is now waiting for it to be accepted by the client Freelancer
`Pending payment` `ID=4` Client has accepted the task and is now to pay for it Client
`Completed` `ID=5` Task has been paid Client
`Declined by contractor` `ID=6` Freelancer has declined the task Freelancer
`Rejected by client` `ID=8` Client has rejected a completed task Client
`Waiting for contractor to confirm rejection` `ID=11` Client has rejected the task, and the freelancer needs to confirm the rejection Client
`Payment queued` `ID=12` Client has initiated the payment, but it is still in progress. After the processing completes, the task status will automatically change to Completed (`ID=5`). If this task status persists for long, please contact Support Client
`Dispute initiated` `ID=13` Freelancer has opted to dispute the task by pressing the respective button and is awaiting a response from the client Freelancer
`Client approval` `ID=14` If the freelancer does not complete the task before the deadline, the client needs to either extend the deadline or cancel the task Toggles automatically upon the deadline
`Change approval` `ID=16` Client has proposed changes to some task parameters and is awaiting a response from the freelancer Client

Task Management

This section details requests to retrieve tasks, create tasks and change task statuses.

Retrieving Task List

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/tasks?filter[creatorId]=123" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."

Sample response

HTTP status code: 200 OK

{
  "items": [
    {
    "attributes":: {
    "id": 78,
    "title": "Типы 3D-визуализации",
    "titleEn": "3D-visualisation types",
    "description": "Description",
    "descriptionEn": "Description",
    "type": "multiselect",
    "attrTypeId": "18",
    "values": [
    {
    "title": "Текстурирование",
    "titleEn": "Texturing",
    "id": 63,
    }
    ]
    "options": [
    {
    "id": 59,
    "value": "Low poly",
    "valueEn": "Low poly",
    }
    ]
    }
    ],
      "category": {
        "id": 20,
        "title": "Управление размещением медийной рекламы",
        "titleEn": "ATL advertising management",
        "titleDoc": "Услуги по управлению размещением рекламных материалов  на интерNo сайтах",
        "titleDocEn": "Services on managing  advertising materials' placement at websites"
      },
      "parentCategory": {
        "id": 2,
        "title": "Интер-реклама",
        "titleEn": "Internet advertising"
      },
      "commissionAmount": 7.29,
      "commissionPercent": 9,
      "copyright": false,
      "createType": "API",
      "currency": {
        "currency": "EUR",
        "id": 3
      },
      "customer": {
        "id": 2955,
        "title": "ааап"
      },
      "creator": {
        "id": 100740,
        "fullName": "Jack Kris"
      },
      "worker": {
        "id": 100871,
        "email": "[email protected]",
        "firstName": "Ivan",
        "lastName": "Ivanov",
        "isVerified": true
      },
      "dateCreated": "2021-08-06 11:17:13",
      "dateAccepted": null,
      "dateEnd": "2021-08-07 14:17:13",
      "dateFinished": null,
      "datePaid": "2021-08-06 14:17:13",
      "datePayAt": null,
      "documentDate": "2021-08-06 14:17:13",
      "description": "Some task description",
      "uuid": "123e4567-e89b-12d3-a456-426655440000",
      "files": [
        {
          "id": 252479,
          "name": "0cbb62da64de73d3bb82b366d37b573f.pdf",
          "typeId": 5,
          "ownerId": 100556
        }
      ],
      "id": 583689,
      "needReport": false,
      "price": 81,
      "state": 5,
      "title": "freel tailand",
      "deadline": {
        "type": 0,
        "triggerDate": null,
        "isComingUp": false
      },
      "hold": {
        "type": "without_hold",
        "isActive": false
      },
      "insurance": {
        "status": 0
      },
      "group": {
        "id": 654,
        "title": "группа 654"
      },
      "messageCount": 0,
      "shareCommission": 1,
      "sharedCommission": 10,
      "activeDispute": null,
      "activeChangesetId": null
    }
  ]
  "pagination": {
    "count": 20,
    "total": 102,
    "perPage": 20,
    "page": 1,
    "pages": 6
  }
}

This method is used to search tasks using various filters.

Request

HTTP Request
Query parameters
Parameter Type Required Description
filter[creatorId] integer No ID of the user who created the task
filter[workerId] integer No Contractor ID. To get a list of freelancers, use this request
filter[companyId] integer No Company ID. To get a list of companies, use this request
filter[dateCreatedFrom] string No Date the task was created (start of a date range). The format is `YYYY-MM-DD` (for example, `2020-09-03`), and the time is `00:00:00`
filter[dateCreatedTo] string No Date the task was created (end of a date range). The format is `YYYY-MM-DD` (for example, `2020-09-03`), and the time is `23:59:59`
filter[dateEndFrom] string No Date of the task's deadline (start of a date range). The format is `YYYY-MM-DD` (for example, `2020-09-03`), and the time is `00:00:00`
filter[dateEndTo] string No Date of the task's deadline (end of a date range). The format is `YYYY-MM-DD` (for example, `2020-09-03`), and the time is `23:59:59`
filter[dateFinishedFrom] string No Task completion date (start of a date range). The format is `YYYY-MM-DD` (for example, `2020-09-03`), and the time is `00:00:00`
filter[dateFinishedTo] string No Task completion date (end of a date range). The format is `YYYY-MM-DD` (for example, `2020-09-03`), and the time is `23:59:59`
filter[dateReportFrom] string No Date of certificate generation (start of a date range). The format is `YYYY-MM-DD` (for example, `2020-09-03`), and the time is `00:00:00`
filter[dateReportTo] string No Date of certificate generation (end of a date range). The format is `YYYY-MM-DD` (for example, `2020-09-03`), and the time is `23:59:59`
filter[dateAcceptedFrom] string No Date when the client accepts the task (start of a date range). The format is `YYYY-MM-DD` (for example, `2020-09-03`), and the time is `00:00:00`
filter[dateAcceptedTo] string No Date when the client accepts the task (end of a date range). The format is `YYYY-MM-DD` (for example, `2020-09-03`), and the time is `23:59:59`
filter[datePaidFrom] string No Date when the task is paid (start of a date range). The format is `YYYY-MM-DD` (for example, `2020-09-03`), and the time is `00:00:00`
filter[datePaidTo] string No Date when the task is paid (end of a date range). The format is `YYYY-MM-DD` (for example, `2020-09-03`), and the time is `23:59:59`
filter[hasPayout] boolean No Serves to return only the paid tasks. If the value is 0, only tasks without a payout are returned (see [here](#3fae8a1168) for payout requests).
filter[priceFrom] integer No Task price (start of interval)
filter[priceTo] integer No Task price (end of interval)
filter[search] string No Task name or description. Searches text in the task title or description.
filter[state] integer No Task status. You can pass one or several values (e.g., `state[]=2&state[]=3`)
filter[currencyId] integer No Currency ID. Possible values:
  • `1`: RUB
  • `2`: USD
  • `3`: EUR
filter[groupId] integer No Task group ID
filter[deadlineType] integer No Deadline type ID. Possible values:
  • `1`: Soft deadline
  • `2`: Hard deadline
filter[workerTaxationStatus] integer No Freelancer tax status. Possible values:
  • `1`: Individual
  • `3`: Self-employed
  • `4`: Individual entrepreneur
filter[hasCopyright] boolean No Indicates the need to transfer intellectual property rights
filter[hasReport] boolean No Indicates that a report is required when completing a task
filter[payedBy] integer No ID of the user who paid for the task
sort string No Attribute that is to serve as the basis for sorting. Possible values:
  • `date_end`: Task deadline
  • `date_finished`: Task completion date
  • `price`: Task price
direction string No Sorting order. Possible values:
  • `asc`: Ascending
  • `desc`: Descending
page integer No Page number for page output
size integer No Number of items per page (20 by default, 500 maximum)
Response

A successful request returns the following response:

Property Type Description
items list List of items
id integer Task ID
attributes object Task attributes
attributes.id integer Attribute ID
attributes.title string Title
attributes.titleEn string Attribute title in English
attributes.description string Attribute description
attributes.descriptionEn string Attribute description in English
attributes.type string Field type (e.g., multiselect)
attributes.attrTypeId integer Field type ID for the attribute
attributes.values object Value
attributes.values.title string Attribute value
attributes.values.titleEn integer Attribute value in English
attributes.values.id object Attribute value ID
attributes.options object List of values (applicable only for fields with value lists: select, multiselect)
attributes.options.id integer Attribute value ID
attributes.options.value string Attribute value
attributes.options.valueEn string Attribute value in English
category object Task category
category.id integer Category ID
category.title string Category name
category.titleEn string Category name in English
category.titleDoc string Category name for accounting documents
category.titleDocEn string Category name for accounting documents (in English)
parentCategory object Task category (parent)
category.id string Task category ID
category.title string Task category name
category.title_en string Task category name in English
commissionAmount float Commission amount
commissionPercent float Commission (as a percentage)
copyright string This property concerns the transfer of intellectual property rights
createType string Indicates how the task was created (via the API or interface)
currency object Task currency
currency.currency string Task currency name
currency.id integer Task currency ID
customer object Client
customer.id string Company ID
customer.title string Company name
creator object User that created the task
creator.id integer ID of the user that created the task
creator.fullName string Full name of the user that created the task
worker object Freelancer
worker.id integer Freelancer ID (returned in a freelancer retrieval request)
worker.email string Freelancer's email
worker.firstName string Freelancer's first name
worker.lastName string Freelancer's last name
worker.isVerified boolean Indicates whether the freelancer is verified or not
dateCreated string Task creation date
dateAccepted string Date when the task was accepted by the client
dateEnd string Date of the task’s deadline
dateFinished string Date when the freelancer completed the task
datePaid string Date of task payment arrival
datePayAt string Date of task payment initiation
documentDate string Date when accounting documents were generated
description string Task description
uuid uuid Task's UUID
needReport boolean Indicates whether a task report is required
price float Task price
state integer Task status
title string Task name
hasPayout boolean Indicates whether a payout has occurred or not
files object Files attached to the task
files.id string File ID
files.name string Filename
files.typeId string File type
files.ownerId string ID of the user that added the file (files can be added by both clients and freelancers)
deadline object Deadline
deadline.type integer Deadline type (1 for soft, 2 for hard)
deadline.triggerDate string Deadline date
deadline.isComingUp boolean Indicates that the deadline is less than 3 days away
group object Task group
group.id integer Task group ID
group.title string Task group name
hold object Holding of funds (escrow)
hold.type string Holding (escrow) type
hold.isActive boolean Indicates whether holding (escrow) is active for the task
insurance object Insurance
insurance.status integer Status of insurance
shareCommission boolean Indicates whether the commission is shared with the freelancer (if 0, the commission is fully paid by the client, if 1, 1% of the client's commission will be compensated by the freelancer)
sharedCommission string The amount of the commission that will be compensated by the freelancer is applicable only if shareCommission = 1
messageCount integer Number of messages
activeDispute boolean Indicates whether there is an open dispute
activeChangesetId integer Indicates whether approval of changes is in progress for the task
issueCode string Error when processing the task (for example, if the client accepts the task while Secure Deal is enabled, but the funds on their balance are insufficient for holding (escrow))
pagination list Paginated output of items
pagination.count integer Number of items returned
pagination.total integer Total items available with the requested filter
pagination.perPage integer Number of items per page
pagination.page integer Page number
pagination.pages integer Total pages

Retrieving Tasks Using Their IDs

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/tasks/c6e8e285-1e0a-4a11-a676-89211c0adccc" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."

Sample response

HTTP status code: 200 OK

{
  "attributes": [
    {
      "attribute": {
        "title": "URL-адрес ",
        "titleEn": "URL-address",
        "type": "1"
      },
      "attributeType": {
        "title": "Адрес сайта",
        "titleEn": "URL adress ",
        "type": "text"
      },
      "values": [
        {
          "title": "http://some.domain.com"
        }
      ]
    }
  ],
  "messages": [],
  "creator": {
    "id": 100740,
    "fullName": "Jack Kris"
  },
  "worker": {
    "id": 100871,
    "email": "[email protected]",
    "firstName": "Ivan",
    "lastName": "Ivanov",
    "isVerified": true
  },
  "files": [],
  "links": [],
  "messageCount": 0,
  "attributes":: {
  "id": 78,
  "title": "Типы 3D-визуализации",
  "titleEn": "3D-visualisation types",
  "description": "Description",
  "descriptionEn": "Description",
  "type": "multiselect",
  "attrTypeId": "18",
  "values": [
  {
  "title": "Текстурирование",
  "titleEn": "Texturing",
  "id": 63,
  }
  ]
  "options": [
  {
  "id": 59,
  "value": "Low poly",
  "valueEn": "Low poly",
  }
  ]
  }
  ],
  "category": {
    "id": 20,
    "title": "Управление размещением медийной рекламы",
    "titleEn": "ATL advertising management",
    "titleDoc": "Услуги по управлению размещением рекламных материалов  на интерNo сайтах",
    "titleDocEn": "Services on managing  advertising materials' placement at websites"
  },
  "parentCategory": {
    "id": 2,
    "title": "ИнтерNo-реклама",
    "titleEn": "Internet advertising"
  },
  "commissionAmount": 7.29,
  "commissionPercent": 9,
  "copyright": false,
  "createType": "API",
  "currency": {
    "currency": "EUR",
    "id": 3
  },
  "customer": {
    "id": 2955,
    "title": "ФИО заказчика"
  },
  "dateCreated": "2021-08-06 11:17:13",
  "dateAccepted": null,
  "dateEnd": "2021-08-07 14:17:13",
  "dateFinished": null,
  "datePaid": "2021-08-06 14:17:13",
  "datePayAt": null,
  "documentDate": "2021-08-06 14:17:13",
  "description": "Some task description",
  "uuid": "123e4567-e89b-12d3-a456-426655440000",
  "id": 583689,
  "needReport": false,
  "price": 81,
  "state": 5,
  "title": "freel tailand",
  "deadline": {
    "type": 0,
    "triggerDate": null,
    "isComingUp": false
  },
  "hold": {
    "type": "without_hold",
    "isActive": false
  },
  "insurance": {
    "status": 0
  },
  "activeDispute": null,
  "activeChangesetId": null,
  "shareCommission": 1,
  "sharedCommission": 10
}

This method is used to retrieve the details of a task using its ID.

Request

HTTP Request
Path parameters

As a path parameter, you must pass either taskId or taskUuid, which can be obtained in the specified request.

Response

A successful request returns the following response:

Property Type Description
items list List of items
id integer Task ID
attributes object Task attributes
attributes.id integer Attribute ID
attributes.title string Title
attributes.titleEn string Attribute title in English
attributes.description string Attribute description
attributes.descriptionEn string Attribute description in English
attributes.type string Field type (e.g., multiselect)
attributes.attrTypeId integer Field type ID for the attribute
attributes.values object Value
attributes.values.title string Attribute value
attributes.values.titleEn integer Attribute value in English
attributes.values.id object Attribute value ID
attributes.options object List of values (applicable only for fields with value lists: select, multiselect)
attributes.options.id integer Attribute value ID
attributes.options.value string Attribute value
attributes.options.valueEn string Attribute value in English
category object Task category
category.id integer Category ID
category.title string Category name
category.titleEn string Category name in English
category.titleDoc string Category name for accounting documents
category.titleDocEn string Category name for accounting documents (in English)
parentCategory object Task category (parent)
category.id string Task category ID
category.title string Task category name
category.title_en string Task category name in English
commissionAmount float Commission amount
commissionPercent float Commission (as a percentage)
copyright string This property concerns the transfer of intellectual property rights
createType string Indicates how the task was created (via the API or interface)
currency object Task currency
currency.currency string Task currency name
currency.id integer Task currency ID
customer object Client
customer.id string Company ID
customer.title string Company name
creator object User that created the task
creator.id integer ID of the user that created the task
creator.fullName string Full name of the user that created the task
worker object Freelancer
worker.id integer Freelancer ID (returned in a freelancer retrieval request)
worker.email string Freelancer's email
worker.firstName string Freelancer's first name
worker.lastName string Freelancer's last name
worker.isVerified boolean Indicates whether the freelancer is verified or not
dateCreated string Task creation date
dateAccepted string Date when the task was accepted by the client
dateEnd string Date of the task’s deadline
dateFinished string Date when the freelancer completed the task
datePaid string Date of task payment arrival
datePayAt string Date of task payment initiation
documentDate string Date when accounting documents were generated
description string Task description
uuid uuid Task's UUID
needReport boolean Indicates whether a task report is required
price float Task price
state integer Task status
title string Task name
hasPayout boolean Indicates whether a payout has occurred or not
files object Files attached to the task
files.id string File ID
files.name string Filename
files.typeId string File type
files.ownerId string ID of the user that added the file (files can be added by both clients and freelancers)
deadline object Deadline
deadline.type integer Deadline type (1 for soft, 2 for hard)
deadline.triggerDate string Deadline date
deadline.isComingUp boolean Indicates that the deadline is less than 3 days away
group object Task group
group.id integer Task group ID
group.title string Task group name
hold object Holding of funds (escrow)
hold.type string Holding (escrow) type
hold.isActive boolean Indicates whether holding (escrow) is active for the task
insurance object Insurance
insurance.status integer Status of insurance
messageCount integer Number of messages
shareCommission boolean Indicates whether the commission is shared with the freelancer (if 0, the commission is fully paid by the client, if 1, 1% of the client's commission will be compensated by the freelancer)
sharedCommission string The amount of the commission that will be compensated by the freelancer is applicable only if shareCommission = 1
activeDispute boolean Indicates whether there is an open dispute
activeChangesetId integer Indicates whether approval of changes is in progress for the task
serviceFeeCompensation integer Freelancer's commission compensation amount
serviceFeeCompensationPercent integer The percentage of the task's cost that determines the freelancer's commission compensation amount

Creating a Task

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/tasks" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -d '{
      "uuid": "123e4567-e89b-12d3-a456-426655440000",
      "categoryId": 37,
      "attributes": [
        {
          "id": 37,
          "value": "1"
        }
      ],
      "acceptanceFileIds": [
        100
      ],
      "copyright": true,
      "needReport": true,
      "title": "string",
      "description": "string",
      "externalId": "string",
      "fileIds": [
        100
      ],
      "workerId": 1,
      "editGroup": [
        100
      ],
      "deadline": "2022-06-22T08:57:53.299Z",
      "price": 1000,
      "validateOnly": false,
      "needInsurance": false,
      "compensateWorkerServiceFee": false,
      "advData": {
        "endContracts": [
          {
            "uuid": "73d13481-e71c-4edb-b251-a48bbcfa4133",
            "sum": 100
          },
          {
            "uuid": "e923e2f9-f1ed-4cb4-a293-e2d1b21fdac1",
            "sum": 200
          },
          {
            "uuid": "38f680a8-53e8-4bf1-bfde-04bea8351022",
            "sum": 250
          }
        ]
      }
    },
    "shareCommission": 0'

Sample response

HTTP status code: 200 OK

The method is used to create new tasks.

If online ads are shown in Russia, they are subject to the ad labeling law. Therefore, when creating tasks with this service category, you need to pass additional attributes. To learn more, see here.

Request

HTTP Request
Request body
Parameter Type Required Description
uuid string No Task UUID (if not provided, this parameter is determined automatically)
categoryId integer Yes ID of the task's service/work. To retrieve all of the available services and works, use this request
attributes object Yes Task attributes. At least 1 (one) attribute is required. To retrieve all the available task attributes, use this request
attributes.id integer Yes Attribute ID
attributes.value string Yes Task attribute's value. For select-type attributes, you need to provide a text value
acceptanceFileIds array No Files that a freelancer needs to sign to accept the task
copyright boolean No Indicates the need to transfer intellectual property rights
needReport boolean No Indicates the need to attach a report to a completed task
title string Yes Task name
description string Yes Task description
fileIds string No Files to be attached to the task
workerId integer Yes Freelancer ID. To retrieve a list of freelancers, use this request
editGroup array No Task group. To retrieve available groups, use this request
externalId string No D that can be set when creating a task (merchant_txid)
deadline date Yes Task deadline (e.g., 2022-05-19 11:53:03)
price float Yes Task price
needInsurance boolean No Indicates whether the task has insurance 
validateOnly boolean No Determines whether the task will be created. If the value is 1, the system will check if all the conditions for creating a task are met and return a response indicating whether the task can be created (however, no task is created as a result of this action)
advData object No Data for ensuring compliance with the ad labeling law. To learn more, see here. If you need a breakdown (itemization), you can add multiple contracts for each task. If the task's total amount exceeds that of all the contracts, the surplus will be classified as Ad Production. If the total task amount is less, the task will not be created, and an error will be returned instead
advData.endContracts.uuid Uuid No Contract ID for the purposes of the ad labeling law. To learn more, see here
advData.endContracts.sum integer No Contract amount. This parameter is required if the task has more than one contract (several counterparties). If there is only one contract, the parameter is optional. To learn more, see here
shareCommission boolean No Indicates whether the commission is shared with the freelancer (if 0, the commission is fully paid by the client, if 1, 1% of the client's commission will be compensated by the freelancer). If the parameter is not specified, the commission is paid by the client.
Response

A successful request returns UUID of created task.

Retrieving Insurance Info

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/insurance/info" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."

Sample response

HTTP status code: 200 OK

This method is used to obtain information about task insurance for the requested freelancer.

Request

HTTP Request
Request body
Parameter Type Required Description
workerId integer Yes Freelancer ID (returned in a freelancer retrieval request)
categoryId integer Yes Task category (to learn more, see the task category retrieval request)
Response
Property Type Description
canBeInsured boolean Indicates whether the task can be insured
acceptanceRequired boolean Indicates whether confirmation from the freelancer is needed to insure the task
cost float Insurance cost (in rubles)
insureByDefault boolean Indicates whether tasks are going to be automatically insured

Changing Task Status

Sample request

curl -X PUT "https://my.solarstaff.com/api/customer/tasks/c6e8e285-1e0a-4a11-a676-89211c0adccc" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."

Sample response

HTTP status code: 200 OK

This method is used to change the task status based on the freelancer's actions. Before using this request, please contact SolarStaff support to have additional access rights to the service added. You can switch to the following statuses: Start task (ID=2), Complete task (ID=3), Decline task (ID=6), and Confirm rejection if the task was rejected by the client (ID=8). 

There are additional requests for rejecting/declining a task or resuming the work.

Запрос

HTTP запрос
Path parameters
Parameter Type Required Description
taskId integer Either taskId or uuid is required Task ID. To retrieve a list of tasks, use this request.
uuid string Either taskId or uuid is required Task UUID
Тело запроса
Parameter Type Required Description
state integer Yes Task status. The available statuses are: Start task (ID=2), Complete task (ID=3), Decline task (ID=6), and Confirm rejection if the task was rejected by the client (ID=8).
Ответ

A successful request returns an empty response.

Possible errors: 

  • Unsigned offer agreement. If there is a new offer agreement that is required to start a task, the user needs to accept it.

    { "error": "To start the task, please sign the offer agreement", "code": 11 }

Changing Deadline

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/tasks/prolong-deadline" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."

Sample response

HTTP status code: 200 OK

This method is used to extend the task's deadline only for tasks in the "Awaiting action from the client" status.

Запрос

HTTP запрос
Request body
Parameter Type Required Description
taskId integer Either taskId or uuid is required Task ID. To retrieve a list of tasks, use this request.
uuid string Either taskId or uuid is required Task's UUID.
deadline date Yes Date of the new deadline in 2022-07-25T15:00:58.295Z format
Ответ

A successful request returns an empty response.

Checking for Issues Prior to Task Start

Sample request

curl -X GET "http://my.solar-staff.comapi/customer/freelancers/check-task-requirements?taskUuid=837843c9-72e5-48e2-a133-e97e347373af&freelancerUuid=ec304480-5e3f-4bb7-a9e5-dbb49fb673e9" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status code: 200 OK

{
"name": "agreementRequired",

"data"
  :{
  "url": "http://cabinet.solar.localhost/agreement-template?uuid=4b8d3847-5651-40f5-b534-48b273974c5c ",
  "templateUuid": "4b8d3847-5651-40f5-b534-48b273974c5c",
  "code": "forced_update",
  "reason": "

Для работы с задачами необходимо принять новый Договор-оферту.

"
}}

This request indicates whether the freelancer can start the task or if there are any issues preventing it (such as the need to re-sign the offer agreement or get verified). Therefore, this request must be called before changing the task status to Start task (ID=2). Possible issues: 

  • The offer agreement needs to be re-signed. You need to have the new offer agreement shown to the freelancer, make sure they agree to it, and call the "Accept offer on behalf of freelancer" request.
  • Freelancer needs to get verified.
  • Freelancer needs to accept non-disclosure documents (NDA)
  • Requirements related to advertising (such as the need to specify the TIN, OGRNIP, or phone number). To learn more, see the Ad Labeling Law section.

Request

HTTP Request
Path parameters
Parameter Type Required Description
taskUuid uuid Yes Task UUID that is returned upon calling the retrieve task by ID or "retrieve task list" requests
freelancerUuid uuid Yes Freelancer UUID that is returned upon calling the invite new freelancer request

Ответ

If no issues are found, then the response is returned empty.

Property Name Type Description
name string Issue name
data object The details of the document that need to be signed (or any other restriction that must be complied with to start working on the task). If the constraint is related to verification (name=verification), this field will contain an empty object.
data.url string URL of the document that needs to be re-signed
data.templateUuid string Document UUID
data.code string Issue code
reason string Cause of the issue (for example, the task being on a sanctions list and therefore requiring the signing of the offer agreement prior to starting)

Accepting Task

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/tasks/accept" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -d '{
      "uuid": "123e4567-e89b-12d3-a456-426655440000"
    }'

Sample response

HTTP status code: 200 OK

This method is used to accept the results of the freelancer's work. It can only be called on tasks in the Completed status (ID=3).

Request

HTTP Request
Body request
Parameter Type Required Description
taskId integer Either taskId or uuid is required Task ID. To retrieve a list of tasks, use this request.
uuid string Either taskId or uuid is required Task's UUID
Request Payload

No additional parameters are required.

Response

A successful request returns an empty response.

Pay for Task

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/tasks/pay" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -d '{
      "uuid": "123e4567-e89b-12d3-a456-426655440000"
    }'

Sample response

HTTP status code: 200 OK

This method is used to pay for tasks. The funds are debited from the client's balance and credited to the freelancer's balance. This method can only be used to pay for a task that is in the "Pending payment" status (ID = 4)

Request

HTTP Request
Request body
Parameter Type Required Description
taskId integer Either taskId or uuid is required Task ID. To retrieve a list of tasks, use this request.
uuid string Either taskId or uuid is required Task's UUID.
Response

A successful request returns an empty response.

Pay for Task upon Creation

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/tasks/quick-pay" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -d '{
      "taskId": 1
    } '

Sample response

HTTP status code: 200 OK

This method is used to pay for tasks that are in the `New` status. You can create a new task and call this request right away, and the task's status will switch to `Paid` (unlike the previous request, which can only make a task `Paid` from the `Pending payment` status). This method only works for tasks that have no additional documents (offer agreements, NDAs) for the freelancer to sign.

Request

HTTP Request
Request body
Parameter Type Required Description
taskId integer Either taskId or uuid is required Task ID. To retrieve a list of tasks, use this request.
uuid string Either taskId or uuid is required Task's UUID
companyId integer No Company ID
Response

A successful request returns an empty response.

Declining/Rejecting Task

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/tasks/decline 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -d '{
      "taskId": 180012
    }'

Sample response

HTTP status code: 200 OK

This method is used to decline (reject) the task. Depending on the task's status prior to the request, after the request is called the status will change to: 

  • For the statuses New (ID=1), In progress (ID=2), and Waiting for contractor to confirm rejection (ID=11), the new status will be Rejected by client (ID=8).
  • For the statuses Pending payment (ID=4) and Client review (ID=3), the new status will be Waiting for contractor to confirm rejection (ID=11).
  • For the statuses Change approval (ID=16), Dispute initiated (ID=13), Completed (ID=5), Declined by contractor (ID=6), and Waiting for contractor to confirm rejection (ID=11), an error will be returned.

Request

HTTP Request
Request body
Parameter Type Required Description
taskId integer Yes Task ID. To retrieve a list of tasks, use this request.
Response

A successful request returns an empty response.

Resume Task

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/tasks/return-to-work
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -d '{
      "taskId": 180012
    }'

Sample response

HTTP status code: 200 OK

This method is used to resume work on the task. The task can only be returned to the In progress status (ID=2) from Client review (ID=3). For all the other statuses, an error will be returned. See a detailed chart with the main task statuses here.

Request

HTTP Request
Request body
Parameter Type Required Description
taskId integer Yes Task ID. To retrieve a list of tasks, use this request.
Response

A successful request returns an empty response.

Ad Labeling Law

This section lists requests used to create tasks that involve the distribution of advertising in Russia. To learn more, see here.

If you are the end advertiser, then in your task creation request you need to provide the ID of the contract with Solar Staff, which is returned when you request company details for the advertising data operator (contract with Solar Staff has value true for isPrimary parameter).

If you are not the end advertiser but an intermediary, then you need to provide the details of the end customer and their contractor: 

If you need a breakdown (itemization), you can add multiple contracts for each task. If the task amount exceeds that of all added contracts, then the surplus will be classified as Ad Production. To retrieve all the contracts related to the task, use this request.

Providing Customer Details

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/ord/organization" 
        -H  "accept: */*" 
        -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
        -H  "Content-Type: application/json" 
        -d "{
            "externalOrganisationId": "1as7ac19-5y33-4a3a-94b3-b4a26374de4d",
            "fullOpf": "Name", 
            "inn": "11111111",
            "ogrn": "123132", 
            "regionNumber": "12"
        }"
    

Sample response

HTTP status code: 200 OK

This method is used to add customer details. If you are an intermediary, you need to add the details of the end customer: 

  • Provide end customer details
  • Provide the details of the end customer's contractor If you are the end customer's contractor, then when creating a contract, you need to use the UUID returned in the request for your company's details.

Request

HTTP Request
Request body
Parameter Type Required Description
externalOrganisationId uuid Yes Customer UUID
fullOpf string Required for legal entities Form of incorporation and full name
inn string Required for all customers in Russia Taxpayer Identification Number (INN, TIN)
ogrn string No Business Registration Number (OGRN)
fio string Required for individuals and individual entrepreneurs Full name
ogrnip string No Individual Entrepreneur Registration Number (OGRNIP)
registrationNumber string Required for non-Russian legal entities Registration number or its equivalent
phoneNumber string Required for non-Russian individuals Phone number
taxId string Required for non-Russian legal entities Taxpayer identification number or its equivalent in the country of registration
regionNumber string Required for non-Russian customers Country code from the Russian Classification of the World's Countries (OKSM).
paymentNumber string Required for non-Russian individuals Electronic payment instrument number
Response

A successful request returns an empty response.

Retrieving List of Added Customers 

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/ord/organization" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status code: 200 OK

{
  "items": [
  {
    "uuid":"a740f1bf-fc7a-4e68-9ad9-0a23688f3b00",
    "title":"Org title 2",
    "type":"organisation",
    "isPrimary":false
  },
  {
    "uuid":"a740f1bf-fc7a-4e68-9ad9-0a23688f3bfe",
    "title":"Org title 1",
    "type":"organisation",
    "isPrimary":false
  }
  ],
  "pagination":
  {
    "count":2,
    "total":2,
    "perPage":20,
    "page":1,
    "pages":1
  }
}

This method is used to retrieve the list of all the customers you have added.

Request

HTTP Request
Parameters

No additional parameters are required.

Ответ
Property Name Type Description
uuid uuid Customer UUID
title string Customer name
type string Customer type
isPrimary boolean Returns true if this customer was added by you.

Retrieving Customer Details by ID

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/ord/organization/537ed52b-bb6f-452c-bd71-7c82fff7fbf7" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status code: 200 OK

{
  "data":
  {
    "externalOrganisationId":"537ed52b-bb6f-452c-bd71-7c82fff7fbf7",
    "inn":"3664069397",
    "isOpc":true,
    "isPp":true,
    "fio":"",
    "fullOpf":"OOO Test Org",
    "individualAccountDescription":"",
    "legalType":"LEGAL_TYPE_LEGAL",
    "ogrn":"1053600591197",
    "ogrnip":"0",
    "paymentNumber":"",
    "phoneNumber":"",
    "regionNumber":"",
    "platforms":[
      {
        "externalPlatformId":"dbb88349-0b82-45d3-bc6f-b973a2faeb1c",
        "isPlatformOwner":false
      }],
    "postAddress":null,
    "regionNumber":"",
    "registrationNumber":"",
    "shortOpf":"",
    "taxId":"",
    "trustedPerson":"",
    "violationDescription":""
  },
  "uuid":"a740f1bf-fc7a-4e68-9ad9-0a23688f3bfe",
  "title":"Org title 1",
  "type":"organisation",
  "isPrimary":false
}

This method is used to retrieve the details of an added customer.

Request

HTTP Request
Path-parameters

As a path parameter, you must pass customer UUID.

Response
Property Name Type Description
externalOrganisationId string Customer UUID
fullOpf string Form of incorporation and full name
inn string INN (TIN)
isOpc boolean Indicates whether the party is an advertising system operator
isPp boolean Indicates whether the party is an ad distributor
ogrn string Business Registration Number (OGRN)
fio string Full name
individualAccountDescription string Descriptor: legal entity, individual, individual entrepreneur, non-Russian individual, non-Russian legal entity, non-Russian sole proprietor
legalType string Form of ownership
  • LEGAL_TYPE_INVALID: Not defined
  • LEGAL_TYPE_LEGAL: Legal entity
  • LEGAL_TYPE_INDIVIDUAL: Individual
  • LEGAL_TYPE_ENTREPRENEUR: Individual entrepreneur
  • LEGAL_TYPE_FOREIGN_LEGAL: Non-Russian legal entity
  • LEGAL_TYPE_FOREIGN_INDIVIDUAL: Non-Russian individual
  • LEGAL_TYPE_FOREIGN_ENTREPRENEUR: Non-Russian sole proprietor
ogrnip string Individual Entrepreneur Registration Number (OGRNIP)
registrationNumber string Registration number or its equivalent
phoneNumber string Phone number
taxId string Taxpayer number or its equivalent in the country of registration
paymentNumber string Number of electronic payment method (for non-Russian individuals)
platforms.externalPlatformId string Platform UUID. Because Solar Staff does not independently register creatives, platforms are not added either. Therefore, this parameter's value is always empty
platforms.isPlatformOwner boolean Indicates whether the party is the platform's owner. Because Solar Staff does not independently register creatives, platforms are not added either. Therefore, this parameter's value is always empty
postAddress string Postal address
regionNumber string Code of the country of registration according to the [Russian Classification of the World's Countries OKSM.
shortOpf string Form of incorporation and short name
trustedPerson string Position and full name of the person who is entitled to act on behalf of the legal entity without a power of attorney (for legal entities)
violationDescription string Details of any non-compliance with the requirements for online ad distribution on the part of the advertiser, ad distributor, or advertising system operator

Providing Contract Details 

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/ord/contract" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "externalOrganisationCustomerId": "8jk2bc19-5y33-4a3a-94b3-b4a26374de3n",
        "externalOrganisationPerformerId": "1as7ac19-5y33-4a3a-94b3-b4a26374de4d",
        "contractNumber":"1",
        "contractDate": "11.01.2020"
    }"

Sample response

HTTP status code: 200 OK

This method is used to add contract details. After adding the end customer details, you need to add the contract between the end customer and their contractor. There are two scenarios here:

Request

HTTP Request
Path-parameters
Parameter Type Required Description
externalContractId uuid Yes Contract UUID
externalOrganisationCustomerId uuid Yes Initiator (customer) ID. Returned in a request to create or retrieve the details of the customer.
externalOrganisationPerformerId uuid Yes Contractor ID. Returned in a request to create or retrieve the details of the customer.
contractNumber string No Contract number
contractDate string Yes Contract date
contractType string Yes Contract type:
  • CONTRACT_TYPE_INVALID — the contract type is not defined
  • CONTRACT_TYPE_SERVICE — service agreement
  • CONTRACT_TYPE_INTERMEDIARY — intermediary agreement
  • CONTRACT_TYPE_ADDITIONAL_AGREEMENT — additional agreement
subjectType string Yes Information about the subject of the contract:
  • SUBJECT_TYPE_INVALID— information not defined
  • SUBJECT_TYPE_DISTRIBUTION — advertising distribution agreement
  • SUBJECT_TYPE_ORGANISATION — agreement on the organization of advertising distribution
  • SUBJECT_TYPE_INTERMEDIARY — intermediation
  • SUBJECT_TYPE_REPRESENTATION — representation
  • SUBJECT_TYPE_OTHER — other
Response

A successful request returns an empty response.

Retrieve List of Added Contracts 

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/ord/contract" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status code: 200 OK

{
  "items":[
    {
      "uuid":"a740f1bf-fc7a-4e68-9ad9-0a23688f3b01",
      "title":"Contract org1-org2",
      "type":"contract",
      "isPrimary":false
    }
  ],
  "pagination":
  {
    "count":1,
    "total":1,
    "perPage":20,
    "page":1,
    "pages":1
  }
}

This method is used to retrieve a list of all the added contracts.

Request

HTTP Request
Parameters

There are no additional request parameters.

Ответ
Name Type Description
uuid uuid Contract UUID
title string Contract name
type uuid Contract type
isPrimary boolean Indicates whether it is a contract with the end customer

Retrieving Contract Details by ID

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/ord/contract/1as7ac19-5y33-4a3a-94b3-b4a26374de4d" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status code: 200 OK

{
  "data":
  {
    "externalContractId":"a740f1bf-fc7a-4e68-9ad9-0a23688f3b01",
    "contractType":"CONTRACT_TYPE_SERVICE",
    "externalOrganisationCustomerId":"eea5a0b5-4a7c-456b-9b1c-227d6ca6ac9d",
    "externalOrganisationPerformerId":"eea5a0b5-4a7c-456b-9b1c-227d6ca6ac9d",
    "isCreativeReporter":false,
    "actionType":"ACTION_TYPE_INVALID",
    "subjectType":"SUBJECT_TYPE_DISTRIBUTION",
    "contractNumber":"1111",
    "contractDate":"2022-10-20",
    "additionalContractNumber":"",
    "additionalContractNumberDate":"",
    "price":"100.00",
    "withNds":false,
    "externalParentId":"",
    "createdAt":"2022-10-20T09:55:53.277309Z",
    "editedAt":"2022-10-26T20:34:57.839708Z",
    "createdBy":
    {
      "id":"92",
      "email":"[email protected]",
      "name":"\u041b\u0443\u043a\u0430\u0448\u043e\u0432 \u041c\u0430\u043a\u0441\u0438\u043c"
    },
    "editedBy":null
  },
  "uuid":"a740f1bf-fc7a-4e68-9ad9-0a23688f3b01",
  "title":"Contract org1-org2",
  "type":"contract",
  "isPrimary":false
}

This method is used to retrieve information about an added contract based on its UUID.

Request

HTTP Request
Path-parameters

As a path parameter, you must pass contract UUID.

Response
Name Type Description
data.externalContractId uuid Contract UUID
data.externalOrganisationCustomerId uuid Initiator (customer) ID
data.externalOrganisationPerformerId uuid Contractor ID
data.contractType string Contract type
  • CONTRACT_TYPE_INVALID: Contract type is not defined
  • CONTRACT_TYPE_SERVICE: Service contract
  • CONTRACT_TYPE_INTERMEDIARY: Intermediary contract
  • CONTRACT_TYPE_ADDITIONAL_AGREEMENT: Addendum
data.contractNumber string Contract number
data.contractDate string Contract date
data.isCreativeReporter string Indicates whether the contractor is required to register creatives
data.actionType string Actions of the intermediary representative
  • ACTION_TYPE_INVALID: Actions are not defined
  • ACTION_TYPE_CONCLUSION: Signing of contracts
  • ACTION_TYPE_DISTRIBUTION: Ad distribution
  • ACTION_TYPE_COMMERCIAL: Commercial representation
  • ACTION_TYPE_OTHER: Another intermediary action
>
data.subjectType string Information about the contract's subject
  • SUBJECT_TYPE_INVALID: Information is not defined
  • SUBJECT_TYPE_DISTRIBUTION: Ad distribution contract
  • SUBJECT_TYPE_ORGANIZATION: Contract for the organization of ad distribution
  • SUBJECT_TYPE_INTERMEDIARY: Intermediary activities
  • SUBJECT_TYPE_REPRESENTATION: Representation activities
  • SUBJECT_TYPE_OTHER: Other
data.additionalContractNumber string Addendum number (for addenda)
data.additionalContractNumberDate string Addendum date
data.price float Contract price (if applicable)
data.withNds string Indicates whether value-added tax (VAT) was applied to the price
data.externalParentId uuid Parent contract UUID
data.createdAt string Date of adding the contract to the advertising data operator (ADO)
data.editedAt string Date of changing contract data in the ADO
data.createdBy.id integer ID of the user that added the contract
data.createdBy.email string Email of the user that added the contract
data.createdBy.name string Username
data.editedBy string ID of the user that updated the contract details
uuid uuid Contract UUID
title string Contract name
type uuid Contract type
isPrimary boolean Indicates whether it is a contract with the end customer

Retrieving Contract Details by Task ID

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/ord/task-summary/1as7ac19-5y33-4a3a-94b3-b4a26374de4d" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status code: 200 OK

{
  "endContract": {
    "uuid": "4a0355a7-9019-4208-8f86-6becde69ef",
    "title": "100623 (2020-10-15)",
    "type": "contract",
    "customer": {
      "uuid": "96cf28dc-43fe-495e-ae02-db8a8a06fb",
      "title": "ааа",
      "type": "organisation",
      "externalOrganisationId": "96cf28dc-43fe-495e-ae02-db8a8a06fb",
      "inn": "6174387653",
      "isOpc": false,
      "isPp": false,
      "fio": "",
      "fullOpf": "ааа",
      "individualAccountDescription": "",
      "legalAddress": {
        "address": "",
        "locality": "",
        "postcode": ""
      },
      "legalType": "LEGAL_TYPE_LEGAL",
      "ogrn": "22222222",
      "ogrnip": "0",
      "paymentNumber": "",
      "phoneNumber": "",
      "platforms": [],
      "postAddress": {
        "address": "",
        "locality": "",
        "postcode": ""
      },
      "regionNumber": "",
      "registrationNumber": "",
      "shortOpf": "",
      "taxId": "",
      "trustedPerson": "",
      "violationDescription": ""
    },
    "performer": {
      "uuid": "0109ce50-ff03-4c1c-96af-26bf816597fc",
      "title": "ООО ",
      "type": "organisation",
      "externalOrganisationId": "0109ce50-ff03-4c1c-96af-26bf816597fc",
      "inn": "7733228841",
      "isOpc": false,
      "isPp": false,
      "fio": "",
      "fullOpf": "ООО ",
      "individualAccountDescription": "",
      "legalType": "LEGAL_TYPE_LEGAL",
      "ogrn": "1157746300964",
      "ogrnip": "0",
      "paymentNumber": "",
      "phoneNumber": "",
      "platforms": [],
      "postAddress": null,
      "regionNumber": "",
      "registrationNumber": "",
      "shortOpf": "",
      "taxId": "",
      "trustedPerson": "",
      "violationDescription": ""
    },
    "contractSum": null,
    "actionType": "ACTION_TYPE_INVALID",
    "additionalContractNumber": "",
    "additionalContractNumberDate": "",
    "contractDate": "2020-10-15",
    "contractNumber": "100623",
    "contractType": "CONTRACT_TYPE_SERVICE",
    "externalContractId": "4a0355a7-9019-4208-8f86-6becde69e",
    "externalOrganisationCustomerId": "96cf28dc-43fe-495e-ae02-db8a8a06f",
    "externalOrganisationPerformerId": "0109ce50-ff03-4c1c-96af-26bf816597fc",
    "externalParentId": "",
    "isCreativeReporter": false,
    "price": "",
    "subjectType": "SUBJECT_TYPE_INTERMEDIARY",
    "withNds": false
  },
  "endContracts": [
    {
      "uuid": "4a0355a7-9019-4208-8f86-6becde69e",
      "title": "100623 (2020-10-15)",
      "type": "contract",
      "customer": {
        "uuid": "96cf28dc-43fe-495e-ae02-db8a8a06fb0a",
        "title": "ааа",
        "type": "organisation",
        "externalOrganisationId": "96cf28dc-43fe-495e-ae02-db8a8a06fb0a",
        "inn": "6174387653",
        "isOpc": false,
        "isPp": false,
        "fio": "",
        "fullOpf": "ааа",
        "individualAccountDescription": "",
        "legalAddress": {
          "address": "",
          "locality": "",
          "postcode": ""
        },
        "legalType": "LEGAL_TYPE_LEGAL",
        "ogrn": "22222222",
        "ogrnip": "0",
        "paymentNumber": "",
        "phoneNumber": "",
        "platforms": [],
        "postAddress": {
          "address": "",
          "locality": "",
          "postcode": ""
        },
        "regionNumber": "",
        "registrationNumber": "",
        "shortOpf": "",
        "taxId": "",
        "trustedPerson": "",
        "violationDescription": ""
      },
      "performer": {
        "uuid": "0109ce50-ff03-4c1c-96af-26bf816597fc",
        "title": "ООО "Солар Стафф Рус"",
        "type": "organisation",
        "externalOrganisationId": "0109ce50-ff03-4c1c-96af-26bf816597fc",
        "inn": "7733228841",
        "isOpc": false,
        "isPp": false,
        "fio": "",
        "fullOpf": "ООО "Солар Стафф Рус"",
        "individualAccountDescription": "",
        "legalType": "LEGAL_TYPE_LEGAL",
        "ogrn": "1157746300964",
        "ogrnip": "0",
        "paymentNumber": "",
        "phoneNumber": "",
        "platforms": [],
        "postAddress": null,
        "regionNumber": "",
        "registrationNumber": "",
        "shortOpf": "",
        "taxId": "",
        "trustedPerson": "",
        "violationDescription": ""
      },
      "contractSum": 4000,
      "actionType": "ACTION_TYPE_INVALID",
      "additionalContractNumber": "",
      "additionalContractNumberDate": "",
      "contractDate": "2020-10-15",
      "contractNumber": "100623",
      "contractType": "CONTRACT_TYPE_SERVICE",
      "externalContractId": "4a0355a7-9019-4208-8f86-6becde69ef5a",
      "externalOrganisationCustomerId": "96cf28dc-43fe-495e-ae02-db8a8a06fb0a",
      "externalOrganisationPerformerId": "0109ce50-ff03-4c1c-96af-26bf816597fc",
      "externalParentId": "",
      "isCreativeReporter": false,
      "price": "",
      "subjectType": "SUBJECT_TYPE_INTERMEDIARY",
      "withNds": false
    },
    {
      "uuid": "54963b34-7840-43a3-a668-5f6d95ff30bc",
      "title": "продв.реш.123 (2023-06-03)",
      "type": "contract",
      "customer": {
        "uuid": "e2ce0768-0ff1-49b7-834e-8e38ed36bd83",
        "title": "Продвинутые решения",
        "type": "organisation",
        "externalOrganisationId": "e2ce0768-0ff1-49b7-834e-8e38ed36bd83",
        "inn": "4975396448",
        "isOpc": false,
        "isPp": false,
        "fio": "",
        "fullOpf": "Продвинутые решения",
        "individualAccountDescription": "",
        "legalAddress": {
          "address": "",
          "locality": "",
          "postcode": ""
        },
        "legalType": "LEGAL_TYPE_LEGAL",
        "ogrn": "0",
        "ogrnip": "0",
        "paymentNumber": "",
        "phoneNumber": "",
        "platforms": [],
        "postAddress": {
          "address": "",
          "locality": "",
          "postcode": ""
        },
        "regionNumber": "",
        "registrationNumber": "",
        "shortOpf": "",
        "taxId": "4975396448",
        "trustedPerson": "",
        "violationDescription": ""
      },
      "performer": {
        "uuid": "96cf28dc-43fe-495e-ae02-db8a8a06fb0a",
        "title": "ааа",
        "type": "organisation",
        "externalOrganisationId": "96cf28dc-43fe-495e-ae02-db8a8a06fb0a",
        "inn": "6174387653",
        "isOpc": false,
        "isPp": false,
        "fio": "",
        "fullOpf": "ааа",
        "individualAccountDescription": "",
        "legalAddress": {
          "address": "",
          "locality": "",
          "postcode": ""
        },
        "legalType": "LEGAL_TYPE_LEGAL",
        "ogrn": "22222222",
        "ogrnip": "0",
        "paymentNumber": "",
        "phoneNumber": "",
        "platforms": [],
        "postAddress": {
          "address": "",
          "locality": "",
          "postcode": ""
        },
        "regionNumber": "",
        "registrationNumber": "",
        "shortOpf": "",
        "taxId": "",
        "trustedPerson": "",
        "violationDescription": ""
      },
      "contractSum": 200,
      "actionType": "ACTION_TYPE_OTHER",
      "additionalContractNumber": "",
      "additionalContractNumberDate": "",
      "contractDate": "2023-06-03",
      "contractNumber": "продв.реш.123",
      "contractType": "CONTRACT_TYPE_SERVICE",
      "externalContractId": "54963b34-7840-43a3-a668-5f6d95ff30bc",
      "externalOrganisationCustomerId": "e2ce0768-0ff1-49b7-834e-8e38ed36bd83",
      "externalOrganisationPerformerId": "96cf28dc-43fe-495e-ae02-db8a8a06fb0a",
      "externalParentId": "",
      "isCreativeReporter": false,
      "price": "",
      "subjectType": "SUBJECT_TYPE_INTERMEDIARY",
      "withNds": true
    }
  ],
  "customerContract": {
    "uuid": "4a0355a7-9019-4208-8f86-6becde69ef5a",
    "title": "100623 (2020-10-15)",
    "type": "contract",
    "customer": {
      "uuid": "96cf28dc-43fe-495e-ae02-db8a8a06fb0a",
      "title": "ааа",
      "type": "organisation",
      "externalOrganisationId": "96cf28dc-43fe-495e-ae02-db8a8a06fb0a",
      "inn": "6174387653",
      "isOpc": false,
      "isPp": false,
      "fio": "",
      "fullOpf": "ааа",
      "individualAccountDescription": "",
      "legalAddress": {
        "address": "",
        "locality": "",
        "postcode": ""
      },
      "legalType": "LEGAL_TYPE_LEGAL",
      "ogrn": "22222222",
      "ogrnip": "0",
      "paymentNumber": "",
      "phoneNumber": "",
      "platforms": [],
      "postAddress": {
        "address": "",
        "locality": "",
        "postcode": ""
      },
      "regionNumber": "",
      "registrationNumber": "",
      "shortOpf": "",
      "taxId": "",
      "trustedPerson": "",
      "violationDescription": ""
    },
    "performer": {
      "uuid": "0109ce50-ff03-4c1c-96af-26bf816597fc",
      "title": "ООО "Солар Стафф Рус"",
      "type": "organisation",
      "externalOrganisationId": "0109ce50-ff03-4c1c-96af-26bf816597fc",
      "inn": "7733228841",
      "isOpc": false,
      "isPp": false,
      "fio": "",
      "fullOpf": "ООО "Солар Стафф Рус"",
      "individualAccountDescription": "",
      "legalType": "LEGAL_TYPE_LEGAL",
      "ogrn": "1157746300964",
      "ogrnip": "0",
      "paymentNumber": "",
      "phoneNumber": "",
      "platforms": [],
      "postAddress": null,
      "regionNumber": "",
      "registrationNumber": "",
      "shortOpf": "",
      "taxId": "",
      "trustedPerson": "",
      "violationDescription": ""
    },
    "contractSum": null,
    "actionType": "ACTION_TYPE_INVALID",
    "additionalContractNumber": "",
    "additionalContractNumberDate": "",
    "contractDate": "2020-10-15",
    "contractNumber": "100623",
    "contractType": "CONTRACT_TYPE_SERVICE",
    "externalContractId": "4a0355a7-9019-4208-8f86-6becde69ef5a",
    "externalOrganisationCustomerId": "96cf28dc-43fe-495e-ae02-db8a8a06fb0a",
    "externalOrganisationPerformerId": "0109ce50-ff03-4c1c-96af-26bf816597fc",
    "externalParentId": "",
    "isCreativeReporter": false,
    "price": "",
    "subjectType": "SUBJECT_TYPE_INTERMEDIARY",
    "withNds": false
  },
  "workerAgreement": {
    "customerName": "TMS Solarweb ltd",
    "customerTaxValue": "HE 329931",
    "customerPhone": "+35-725-378-701",
    "performerName": "Смит Вессен",
    "performerPhone": "78679098776",
    "performerCountry": "RU",
    "performerTaxValue": "743937218239",
    "contractNumber": "16561",
    "contractDate": "2021-05-01",
    "sum": 4200,
    "currency": {
      "currency": "RUB",
      "id": 1
    }
  }
}

This method is used to retrieve contract details using a task UUID.

Request

HTTP Request
Path parameters

As a path parameter, you must pass task UUID.

Response
Name Type Description
endContract.uuid uuid Contract UUID
endContract.title string Contract name
endContract.type string Contract type
endContract.customer object Customer in the contract
endContract.performer object Contractor
endContract.contractSum string Contract amount
endContract.actionType string Actions of the intermediary representative
  • ACTION_TYPE_INVALID: Actions are not defined
  • ACTION_TYPE_CONCLUSION: Signing of contracts
  • ACTION_TYPE_DISTRIBUTION: Ad distribution
  • ACTION_TYPE_COMMERCIAL: Commercial representation
  • ACTION_TYPE_OTHER: Another intermediary action
endContract.additionalContractNumber string Addendum number (for addenda)
endContract.additionalContractNumberDate string Addendum date
endContract.contractDate string Contract date
endContract.contractNumber string Contract number
endContract.contractType string Contract type
  • CONTRACT_TYPE_INVALID: Contract type is not defined
  • CONTRACT_TYPE_SERVICE: Service contract
  • CONTRACT_TYPE_INTERMEDIARY: Intermediary contract
  • CONTRACT_TYPE_ADDITIONAL_AGREEMENT: Addendum
endContract.externalContractId string Parent contract number
endContract.externalOrganisationCustomerId string Customer ID in the parent contract
endContract.externalOrganisationPerformerId string Contractor ID in the parent contract
endContract.externalParentId string Parent contract UUID
endContract.isCreativeReporter string Indicates whether the contractor is required to register creatives
endContract.price float Contract price (if applicable)
endContract.subjectType string Information about the contract's subject
  • SUBJECT_TYPE_INVALID: Information is not defined
  • SUBJECT_TYPE_DISTRIBUTION: Ad distribution contract
  • SUBJECT_TYPE_ORGANIZATION: Contract for the organization of ad distribution
  • SUBJECT_TYPE_INTERMEDIARY: Intermediary activities
  • SUBJECT_TYPE_REPRESENTATION: Representation activities
  • SUBJECT_TYPE_OTHER: Other
endContract.withNds string Indicates whether value-added tax (VAT) was applied to the price
endContracts string Contract UUID
endContract object All contracts in the counterparty chain. The object's structure mirrors that of `endContract`
customerContract object End contract of the first customer. The object's structure mirrors that of endContract
workerAgreement.customerName string Customer's name in the contract with the contractor
workerAgreement.customerTaxValue string Customer's taxpayer ID number in the contract with the contractor
workerAgreement.customerPhone string Customer's phone number in the contract with the contractor
workerAgreement.performerName string Contractor name
workerAgreement.performerPhone string Phone number 
workerAgreement.performerCountry string Contractor's country
workerAgreement.performerTaxValue string Contractor's taxpayer ID number
workerAgreement.contractNumber string Contract number
workerAgreement.contractDate string Contract date
workerAgreement.sum string Contract amount
workerAgreement.currency.currency string Contract currency (as listed therein)
workerAgreement.currency.id integer Currency ID in the contract

Task Chat

Clients and freelancers can leave messages within tasks. This section details how you can retrieve existing messages or post new ones. 

Retrieving Task Messages

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/tasks/583689/messages" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."

This method is used to retrieve messages from a given task. 

Request

HTTP Request
Path-parameters

As a path parameter, you must pass either task ID.

Adding Task Messages

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/tasks/messages" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d  '{
            "taskId":583689,
            "message:"Task is ready"
        }'

Sample response

HTTP status code: 200 OK

This method is used to add a message to a task. Messages have the authorized user as their sender.

Request

HTTP Request
Request body
Parameter Type Required Description
taskId integer Yes Task ID
message string Yes Text of the message
Response

A successful request returns an empty response.

Task Group

Retrieving Task Groups

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/task-groups" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."

Sample response

HTTP status code: 200 OK

{
  "items": [
    {
      "id": 650,
      "companyId": 2955,
      "color": "FFFFFF",
      "title": "string",
      "createdAt": "2021-12-01 20:59:52"
    }
  ],
  "pagination": {
    "count": 3,
    "total": 3,
    "perPage": 20,
    "page": 1,
    "pages": 1
  }
}

This method is used to get a list of task groups.

Request

HTTP Request
Parameters

There are no additional request parameters.

Ответ
Property Name Type Description
items object Task groups
items.id integer Task group ID
items.companyId integer Client ID
items.color string Group icon color
items.title string Group name
items.createdAt string Date of task group creation
pagination object Pages
pagination.count integer Current page
pagination.total integer Number of pages
pagination.perPage integer Number of tasks per page
pagination.page integer Current page
pagination.pages integer Number of pages

Renaming Task Group

Sample request

curl -X PUT "https://my.solarstaff.com/api/customer/task-groups" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "groupId":650,
        "title":"new name"
    }"

Sample response

HTTP status code: 200 OK

{
  "actorId": 100740,
  "companyId": 2955,
  "groupId": 650,
  "title": "new name"
}

This method is used to change the name of a task group.

Request

HTTP Request
Request body
Parameter Type Required Description
groupId integer Yes Group ID
title string Yes New task group name
Ответ
Property Name Type Description
actorId integer ID of the user that updated the task group name
companyId integer Company ID
groupId integer Task group ID
title string Task group name

Creating Task Groups

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/task-groups" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "title": "new task group"
    }"

Sample response

HTTP status code: 200 OK

{
  "actorId": 100740,
  "companyId": 2955,
  "title": "new task group"
}

This method is used to create a task group.

Запрос

HTTP запрос
Request body
Parameter Type Required Description
title string Yes New task group name
Ответ
Property Name Type Description
actorId integer ID of the user that requested to create the tasks
companyId integer Company ID
title string Task group name

Deleting Task Groups

Sample request

curl -X DELETE "https://my.solarstaff.com/api/customer/task-groups" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "groupId": 650
    }"

Sample response

HTTP status code: 200 OK

{
  "actorId": 100740,
  "companyId": 2955,
  "groupId": 650
}

This method is used to delete a task group.

Request

HTTP Request
Request body
Parameter Type Required Description
groupId integer Yes Task group ID
Ответ
Property Name Type Description
actorId integer ID of the user that requested to create the tasks
companyId integer Company ID
groupId integer Task group ID

Task Files

Adding Files to Task

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/tasks/files" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -d '{
      "uuid": "123e4567-e89b-12d3-a456-426655440000",
      "file": "/Users/solar/tmp/1c_report_example.xml",
      "type": "5"
    }'  

Sample response

HTTP status code: 200 OK

This method is used to add files to the task.

Request

HTTP Request
Request body
Parameter Type Required Description
file string Yes File path (for example, /Users/solar/tmp/1c_report_example.xml)
taskId integer Either taskId or uuid is required Task ID. To retrieve a list of tasks, use this request.
uuid string Either taskId or uuid is required Task's UUID. 
type integer Yes File type. Possible values:
  • 5: Transfer of rights in the task
Response

A successful request returns an empty response.

Freelancers

The section details methods for managing freelancers, including Invite a freelancer, Change freelancer details, and Remove freelancer from the client's team.

Retrieving Freelancer List

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/freelancers?filter[taxationStatusId]=1" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status code: 200 OK

{
  "items": [
    {
      "id": 0,
      "uuid": "1as7ac19-5y33-4a3a-94b3-b4a26374de4d"
      "email": "string",
      "name": "string",
      "taxationStatusId": 0,
      "taxationBlockedTill": "string",
      "categoryTitle": "string",
      "categoryTitleEn": "string",
      "details": {
        "firstName": "string",
        "lastName": "string",
        "note": "string",
        "specialization": "string"
      },
      "country": "AM",
      "isVerified": true,
      "isInviteSent": true,
      "inviteSentAt": "2021-12-23T18:48:40.800Z",
      "registerDate": "2021-12-23T18:48:40.800Z",
      "isRegistered": true
    }
  ],
  "pagination": {
    "count": 20,
    "total": 41,
    "perPage": 20,
    "page": 1,
    "pages": 3
  }
}

This request is used to retrieve a list of freelancers.

Request

HTTP Request
Query parameters
Parameter Type Required Description
filter[taxationStatusId] integer Yes Tax status ID. Possible values:
  • 1: Individual
  • 3: Self-employed
  • 4: Individual entrepreneur
filter[isVerified] boolean Yes Indicates whether the freelancer account is verified
filter[isInviteEmailSent] boolean Yes Indicates whether an invite has been sent to the freelancer
filter[dateInvitedFrom] string Yes Invite date (start of interval)
filter[dateInvitedTo] string Yes Invite date (end of interval)
page integer No Page number for page output
size integer No Number of items per page (20 by default, 500 maximum)

Response

Property Name Type Description
items list Freelancer list
items.id integer Freelancer ID
items.uuid uuid Freelancer UUID
items.email string Freelancer's email
items.name string Freelancer name
items.taxationStatusId integer Freelancer's tax status
items.taxationBlockedTill integer Date until which the tax status cannot be changed
items.categoryTitle string Freelancer specialization
items.categoryTitleEn string Specialization name in English
items.details object Freelancer's personal details
items.details.firstName string Freelancer's first name
items.details.lastName string Freelancer's last name
items.details.note string Freelancer description
items.details.specialization string Freelancer specialization
items.country string Code of the freelancer's country (two letters, like AM for Armenia)
items.isVerified boolean Indicates whether the account is verified
items.isInviteSent boolean Indicates that an invite has been sent
items.inviteSentAt string Date when the invite was sent
items.registerDate string Registration date
items.isRegistered boolean Indicates that the freelancer has accepted the invite and provided personal details
items.isTaxPaymentAllowed boolean Indicates whether automatic tax payment is enabled
pagination list Paginated output
pagination.count integer Number of items returned
pagination.total integer Total items available with the requested filter
pagination.perPage integer Number of items per page
pagination.page integer Number of items per page
pagination.pages integer Total pages

Finding Freelancers by Email

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/freelancer-by-email/{email}" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status code: 200 OK

{
  "id": 1,
  "uuid": "abc123",
  "email": "[email protected]",
  "name": "John Doe",
  "taxationStatusId": 2,
  "taxationBlockedTill": "2023-12-31",
  "categoryTitle": "Категория",
  "categoryTitleEn": "Category",
  "details": {
    "firstName": "Иван",
    "lastName": "Иванов",
    "note": "Примечание",
    "specialization": "Специализация"
  },
  "isVerified": true,
  "country": "RU",
  "isInviteSent": true,
  "inviteSentAt": "2023-11-16T10:44:40.694Z",
  "registerDate": "2023-11-15T15:30:00.000Z",
  "isRegistered": true,
  "isTaxPaymentAllowed": true,
  "emailConfirmationStatus": 1,
  "phoneConfirmationStatus": 1
}

This request is used to find a freelancer by their email.

Request

HTTP Request
Path-parameters

As a path parameter, you must pass freelancer's email.

Response

Property Name Type Description
id integer Freelancer ID
uuid integer Freelancer UUID
email string Freelancer's email
name string Freelancer name
taxationStatusId integer Freelancer's tax status
taxationBlockedTill integer Date until which the tax status cannot be changed
categoryTitle string Freelancer specialization
categoryTitleEn string Specialization name in English
details object Freelancer's personal details
details.firstName string Freelancer first name
details.lastName string Freelancer's last name
details.note string Freelancer description
details.specialization string Freelancer specialization
country string Code of the freelancer's country (two letters, like AM for Armenia)
isVerified boolean Indicates whether the account is verified
isInviteSent boolean Indicates that an invite has been sent
inviteSentAt string Date when the invite was sent
registerDate string Registration date
isRegistered boolean Indicates that the freelancer has accepted the invite and provided personal details
isTaxPaymentAllowed boolean Indicates whether automatic tax payment is enabled
emailConfirmationStatus boolean Indicates whether the freelancer's email is confirmed
phoneConfirmationStatus boolean Indicates whether the freelancer's phone number is confirmed

Finding Freelancers by phone number

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/freelancer-by-phone/{phone number}" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status code: 200 OK

{
  "id": 1,
  "uuid": "abc123",
  "email": "[email protected]",
  "name": "John Doe",
  "taxationStatusId": 2,
  "taxationBlockedTill": "2023-12-31",
  "categoryTitle": "Категория",
  "categoryTitleEn": "Category",
  "details": {
    "firstName": "Иван",
    "lastName": "Иванов",
    "note": "Примечание",
    "specialization": "Специализация"
  },
  "isVerified": true,
  "country": "RU",
  "isInviteSent": true,
  "inviteSentAt": "2023-11-16T10:44:40.694Z",
  "registerDate": "2023-11-15T15:30:00.000Z",
  "isRegistered": true,
  "isTaxPaymentAllowed": true,
  "emailConfirmationStatus": 1,
  "phoneConfirmationStatus": 1
}

This request is used to find a freelancer by their phone number.

Request

HTTP Request
Path-parameters

As a path parameter, you must pass freelancer's phone number.

Response

Property Name Type Description
id integer Freelancer ID
uuid integer Freelancer UUID
email string Freelancer's email
name string Freelancer name
taxationStatusId integer Freelancer's tax status
taxationBlockedTill integer Date until which the tax status cannot be changed
categoryTitle string Freelancer specialization
categoryTitleEn string Specialization name in English
details object Freelancer's personal details
details.firstName string Freelancer first name
details.lastName string Freelancer's last name
details.note string Freelancer description
details.specialization string Freelancer specialization
country string Code of the freelancer's country (two letters, like AM for Armenia)
isVerified boolean Indicates whether the account is verified
isInviteSent boolean Indicates that an invite has been sent
inviteSentAt string Date when the invite was sent
registerDate string Registration date
isRegistered boolean Indicates that the freelancer has accepted the invite and provided personal details
isTaxPaymentAllowed boolean Indicates whether automatic tax payment is enabled
emailConfirmationStatus boolean Indicates whether the freelancer's email is confirmed
phoneConfirmationStatus boolean Indicates whether the freelancer's phone number is confirmed

Retrieving Freelancer Details

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/freelancers/12" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status code: 200 OK

{
  "id": 12,
  "email": "[email protected]",
  "name": "Ivanich",
  "taxationStatusId": 0,
  "taxationBlockedTill": "",
  "categoryTitle": "Разработчик",
  "categoryTitleEn": "Developer",
  "details": {
    "firstName": "Иван",
    "lastName": "Иванов",
    "note": "",
    "specialization": "Developer"
  },
  "country": "AM",
  "isVerified": true,
  "isInviteSent": true,
  "inviteSentAt": "2021-12-23T18:48:40.800Z",
  "registerDate": "2021-12-23T18:48:40.800Z",
  "isRegistered": true
}

This request is used to retrieve the freelancer's data using their ID or UUID.

Request

HTTP Request
Path-parameters

As a path parameter, you must pass either freelancer ID or UUID.

Ответ

Property Name Type Description
id integer Freelancer ID
uuid integer Freelancer UUID
email string Freelancer's email
phone string Freelancer's phone
name string Freelancer name
taxationStatusId integer Freelancer's tax status
taxationBlockedTill integer Date until which the tax status cannot be changed
categoryTitle string Freelancer specialization
categoryTitleEn string Specialization name in English
details object Freelancer's personal details
details.firstName string Freelancer's first name
details.lastName string Freelancer's last name
details.note string Freelancer description
details.specialization string Freelancer specialization
country string Code of the freelancer's country (two letters, like AM for Armenia)
isVerified boolean Indicates whether the account is verified
isInviteSent boolean Indicates that an invite has been sent
inviteSentAt string Date when the invite was sent
isRegistered boolean Indicates that the freelancer has accepted the invite and provided personal details
isTaxPaymentAllowed boolean Indicates whether automatic tax payment is enabled
emailConfirmationStatus boolean Indicates whether the freelancer's email is confirmed
phoneConfirmationStatus boolean Indicates whether the freelancer's phone number is confirmed

Inviting Freelancers

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/freelancers" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "email": "[email protected]",
        "note": "new developer",
        "inEnglish": true,
        "sendEmail": true
      }"

Sample response

HTTP status code: 200 OK

{
  "uuid": "b2e2671d-f850-493f-83ba-f236d3192974"
}

This request is used to add freelancers to a team. When called, this request results in a freelancer being added to your team. You can add freelancers to a team one of two ways:

  • Using their email. Pass the email in the request that is detailed below. If the freelancer has not signed up for Solar Staff yet, they will receive an invite to the specified email and use it to provide personal details.
  • Using their phone number. In this case, it is necessary to provide the phone number. An invitation will not be sent in this case. After installing the application or registering for the service, the freelancer will be prompted to complete the full registration form.

The request will return the freelancer's UUID, which you can then use in the following requests: Retrieve freelancer details, Remove freelancer from team, Retrieve payment method details, and Add new payment method. Please note that you cannot set a custom UUID for a new freelancer: the service will generate it automatically when the freelancer signs up.

Request

HTTP Request
Request body
Parameter Type Required Description
email string Required unless phone is passed Freelancer's email
phone string Required unless email is passed Freelancer's phone number (numbers only, no spaces or special characters)
country string Yes Letter code of the freelancer's country. For a list of countries, see this request
firstName string No Freelancer's first name
lastName string No Freelancer's last name
middleName string No Freelancer's middle name
city string No City
address string No Address
postalCode string No Postal code
note string No Freelancer description
inEnglish boolean No Indicates that the invite must be sent in English
sendEmail boolean No Indicates whether an email is to be sent or not. If not, the freelancer will be added to the client's team without receiving an email.

If the optional fields are passed, then after following the invite link or entering the phone number (if phone was passed in the request), the freelancer will see the provided values and will only need to confirm the registration.

Response

Property Name Type Description
uuid string Freelancer UUID

Editing Profile Details

Sample request

curl -X PUT "https://my.solarstaff.com/api/customer/freelancers" 
    -H  "Accept: application/json" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "freelancerId": 11,
        "firstName": "Ivan",
        "lastName": "Ivanov",
        "note": "description",
        "specialization": "25",
        "freelancerUuid": "8e947213-c114-41ec-a9ae-0242ac130002",
        "companyId": 2
      }"

This request is used to change the freelancer's profile details, such as first name, last name, specialization, or description.

Request

HTTP Request
Request body
Parameter Type Required Description
freelancerId integer Yes Freelancer ID
firstName string No Freelancer's first name
lastName string No Freelancer's last name
note string No Freelancer description
specialization string No Freelancer's specialization. To retrieve a list of specializations, use this request.
freelancerUuid uuid No Freelancer UUID
companyId integer No Company ID

Response

A successful request returns an empty response.

Requesting Code to Change Contact Details

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/freelancers/request-code-for-change-contacts" 
    -H  "Accept: application/json" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "freelancerId": 1,
        "email": "[email protected]",
        "phone": "+1234567890"
      } "

This request is used to change a freelancer's contact details, in particular their phone number or email. When sending the request, include the updated values for the freelancer’s contact details and their ID. This request sends a code to the freelancer that must subsequently be included in the /api/customer/freelancers/change-contacts request (further details are provided below).

Request

HTTP Request
Request body
Parameter Type Required Description
freelancerId integer Yes Freelancer ID
email string No Freelancer's email
phone string No Freelancer's phone number

Response

A successful request returns an empty response.

Confirming Change of Contact Details

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/freelancers/change-contacts" 
    -H  "Accept: application/json" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
          "freelancerId": 1,
          "code": "123123",
      }"

To change a freelancer's contact details (phone number, email, or both), use the below request in JSON format. Make sure to include in the request a unique code received after sending a request to change the contact details, as well as the freelancer's ID. If the code is correct, the freelancer's contact details are updated to those specified in the contact details change request.

Request

HTTP Request
Request body
Parameter Type Required Description
freelancerId integer Yes Freelancer ID
code string Yes Code received in the request for contact details change

Response

A successful request returns an empty response.

Generating Verification Link

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/freelancers/verification-link?freelancerId=123" 
    -H  "Accept: application/json" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status code: 200 OK

{
  "terminal_url":"https://link-to-verification-terminal"
}

Account verification is the process of confirming identity details and documents. To learn more about verification, see the Help Center.

This request is used to generate a verification link that you can send to the freelancer.

Request

HTTP Request
Query parameters
Parameter Type Required Description
freelancerId integer Yes Freelancer ID
redirectUrl integer No URL where the freelancer will be redirected after verification

Response

Property Name Type Description
terminal_url string URL of the verification page

Adding Freelancer's Taxpayer ID Number

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/freelancers/add-tax-document" 
    -H  "Accept: application/json" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "freelancerId": 100934,
        "type": "INN",
        "taxNumber": "709849850606"
      } "


      Sample request that includes  UUID:


curl -X POST "https://my.solarstaff.com/api/customer/freelancers/add-tax-document" 
    -H  "Accept: application/json" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "freelancerUuid": "8e947213-c114-41ec-a9ae-0242ac130002",
        "type": "INN",
        "taxNumber": "709849850606"
      }"

This request is used to add a freelancer's taxpayer identification number, like INN for Russia or some other kind of TIN.

Request

HTTP Request
Request body
Parameter Type Required Description
freelancerId integer Either freelancerId or freelancerUuid is required Freelancer ID
freelancerUuid uuid Either freelancerId or freelancerUuid is required Freelancer UUID (for example, 8e947213-c114-41ec-a9ae-0242ac130002)
type string Yes Tax document type. Possible values:
  • INN : For users in Russia
  • UNP:  For users in Belarus
  • CUIT/CUIL : For users in Argentina (please note that CUIT/CUIL is the name of the document, and the value needs to be passed in exactly this form)
  • NIT / CI / CE : For users in Bolivia
  • CPF / CNPJ : For users in Brazil
  • RUT : For users in Chile
  • PASS / TAXID : For users in China
  • NIT / CC / CE / PASS / PEP : For users in Colombia
  • CI / CJ / CR: For users in Costa Rica
  • RN / CE / PASS: For users in the Dominican Republic
  • CI / RUC / PASS / CE : For users in Ecuador
  • RUC`: For users in Panama
  • CI / RUC : For users in Paraguay
  • DNI / RUC / CE / PASS`: For users in Peru
  • PASS / NI / MIL : For users in Tanzania
  • CI / RUT / DE / PASS : For users in Uruguay
taxNumber string Yes Tax document number

Ответ

A successful request returns an empty response.

Removing Freelancers from Team

Sample request

curl -X DELETE "https://my.solarstaff.com/api/customer/freelancers" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "freelancerId": 12
      }"

Sample response

HTTP status code: 200 OK

A successful request returns an empty response.

This request is used to remove a freelancer from the team.

Request

HTTP Request
Query parameters
Parameter Type Required Description
freelancerId integer Either freelancerId or freelancerUuid is required Freelancer ID
freelancerUuid string Either freelancerId or freelancerUuid is required Freelancer UUID (for example, 8e947213-c114-41ec-a9ae-0242ac130002)

Response

A successful request returns an empty response.

Accepting Offer Agreement

Sample request

curl -X POST "https://my.solarstaff.com/api/customer/freelancers/sign-agreement" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "templateUuid": "1as7ac19-5y33-4a3a-94b3-b4a26374de4d",
        "freelancerId": 100934
      }"

Sample response

HTTP status code: 200 OK

A successful request returns an empty response.

This request lets you sign the offer agreement on behalf of the freelancer. The request checking for new offers returns the offer ID that needs to be provided in the Accepting Offer Agreement request and a link for viewing the offer so you can show it to the freelancer.

Request

HTTP Request
Request body
Parameter Type Required Description
freelancerId integer Either freelancerId or freelancerUuid is required Freelancer ID
freelancerUuid uuid Either freelancerId or freelancerUuid is required Freelancer UUID (for example, 8e947213-c114-41ec-a9ae-0242ac130002)
templateUuid uuid Yes Offer UUID

Response

A successful request returns an empty response.

Finances

In Solar Staff, balance is the user's funds in the system. When it comes to the functions and features it offers to freelancers and companies, it is similar to a bank account. Each freelancer has three balances, each in a different currency: rubles, dollars, and euros. A company can only have a balance in one of those currencies. For that reason, requests for information on a freelancer's balance always return information only on the balance whose currency is the same as the company's.

This section contains the following instructions:

Creating Payout for Task

Sample request

curl --location 
  --request POST 'https://my.solarstaff.com/api/customer/tasks/payout' \
  --data-raw '{
        "taskId": 583695,
        "payoutEndpointType": 1,
        "payoutEndpointId": 79093
    }'

Sample response

HTTP status 200 OK

A successful request returns an empty response.

This request is used to transfer the payment for a paid task from the freelancer's balance to their bank card, bank account, or e-wallet. You can only use this request to send funds for a paid task: you cannot just transfer funds that are not tied to any task from the freelancer's balance. In the request, pass the task ID and the target payment method. As an additional parameter, you can specify the base currency to be converted to the target currency. For example, a withdrawal from a ruble-denominated balance to a Kazakhstani bank card requires a conversion to euros, otherwise no payment will occur.

Request

HTTP Request
Request body
Name Type Required Description
taskId integer Either taskId or uuid is required Task ID. To retrieve a list of tasks, use this request.
uuid string Either taskId or uuid is required Task UUID
payoutEndpointType string Yes Payment method type. Possible values:
  • 1: Bank card
  • 2: WebMoney
  •  
  • 6 : Bank account
.
payoutEndpointId integer Yes ID of the payment method added by the freelancer. You can either add a new payment method or select a payment method from those already added by the freelancer.
currencyId integer No ID of the target currency. To view ID values, use the request for retrieving a list of currencies

Response

A successful request returns an empty response.

Retrieving Payout Status Using Task Number

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/customer/tasks/payout/432453' \

Sample response

HTTP status 200 OK

{
  "payoutStatus": 2
}

This request is used to retrieve the payout status. After creating a payout, you can call this request to verify that the payout has been completed and the money has reached the freelancer.

Request

HTTP Request
Path-parameters

As a path parameter, you must pass either Task ID or UUID. To retrieve a list of tasks, use this request.

Ответ

Property Name Type Description
payoutStatus integer Payout status. Possible values:
  • 1: In progress
  • 2: Completed
  •  
  • 3: Declined
  • 5: Partially completed
  • 10: Created
.

Retrieving Transaction List

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/customer/transactions' \

Sample response

HTTP status 200 OK

{
  "items": [
    {
      "id": 1710153,
      "type": 2,
      "amount": 1030,
      "createdAt": "2021-01-28 10:34:12",
      "currency": {
        "currency": "RUB",
        "id": 1
      },
      "balanceId": 246709
    }
  ],
  "pagination": {
    "count": 20,
    "total": 383,
    "perPage": 20,
    "page": 1,
    "pages": 20
  }
}

This request is used to retrieve a list of all transactions.

Request

HTTP Request
Request body

There are no additional request parameters.

Response

Property Name Type Description
id integer Transaction ID
type integer Transaction type. Possible values:
  • 1: Top-up
  • 2: Withdrawal
  •  
  • 3: Refund
.
amount float Transaction amount
createdAt string Transaction date
currency.currency string Currency name
paycurrency.id integer Currency ID
balanceId integer Balance ID 

Retrieving Freelancer's Payment Methods

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/customer/freelancers/payout-endpoints?freelancerId=1' \
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status 200 OK

{
  "wallets": [
    {
      "createdAt": "2021-07-20 06:33:14",
      "currency": {
        "currency": "RUB",
        "id": 1
      },
      "id": 48998,
      "number": "2099772984",
      "status": 1,
      "walletType": 2,
      "type": 2,
      "ownerId": 100870,
      "autoPay": true
    }
  ],
  "cards": [
    {
      "createdAt": "2021-01-25 10:32:47",
      "currency": {
        "currency": "EUR",
        "id": 3
      },
      "expire": "03/26",
      "holder": "DINA BOOM",
      "id": 79082,
      "number": "5213 24** **** 9877",
      "status": 4,
      "cardType": 1,
      "type": 1,
      "ownerId": 100870,
      "country": "RU",
      "autoPay": true
    }
  ],
  "ibans": []
}

This request is used to retrieve the list of payment methods available to a freelancer.

Request

HTTP Request
Query parameters
Name Type Required Description
freelancerId integer Either freelancerId or freelancerUuid is required Freelancer ID
freelancerUuid string Either freelancerId or freelancerUuid is required Freelancer UUID (for example, 8e947213-c114-41ec-a9ae-0242ac130002)

Response

Property Name Type Description
wallets string E-wallets added by the freelancer
wallets.createdAt string Date added
wallets.currency object Currency
wallets.currency.currency string Currency name
wallets.currency.id integer Currency ID
wallets.id integer E-wallet ID
wallets.number string E-wallet number
wallets.status string Status
wallets.walletType string E-wallet type. Possible values:
  • 3: WebMoney
.
wallets.type string Type of payment method. Possible values:
  • 1: Bank card
  • 2: E-wallet
  •  
  • 6: Bank account
.
wallets.ownerId string Freelancer ID
wallets.autoPay boolean Indicates the activation of automatic payments for the payment method.
cards string URL of the page for adding a payment method
cards.createdAt string Date added
cards.currency object Currency
cards.currency.currency string Currency name
cards.currency.id integer Currency ID
cards.expire string Card expiration date
cards.holder string Cardholder's first and second name
cards.id string Card ID
cards.number string Card number (returns the first 6 and last 4 digits)
cards.status string Status. Possible values:
  • 1: Card linking initiated (the user has opened the page for linking a card)
  •  
  • 3: Bank card blocked
  • 4: Bank card added and verified
  •  
  • 7: Bank card deleted
.
cards.cardType string Bank card type. Possible values:
  • 1: Visa
  • 2 : Mastercard
  • 3: Maestro
  •  
  • 8: Mir
  • 0: Type not defined
.
cards.type string Type of payment method. Possible values:
  • 1: Bank card
  • 2: E-wallet
  •  
  • 6: Bank account
.
cards.ownerId string Freelancer ID
cards.country string Bank card's country of origin
cards.autoPay boolean Indicates the activation of automatic payments for the payment method.
iban string Bank accounts added by the freelancer
iban.createdAt string Date added
iban.currency object Currency
iban.currency.currency string Currency name
iban.currency.id integer Currency ID
iban.id integer Bank account ID
iban.number string Bank account number
iban.status string Status. Possible values:
  • 3: Bank account added, but not yet verified
  • 1: Bank account added and verified
  •  
  • 2: Bank account deleted
.
iban.bankAccountType string Account type. Possible values:
  • 1: SEPA
  • 2: SWIFT
  • 6: BIC
.
iban.type string Type of payment method. Possible values:
  • 1: Bank card
  • 2: E-wallet
  •  
  • 6: Bank account
.
iban.ownerId integer Freelancer ID
iban.autoPay boolean Indicates the activation of automatic payments for the payment method.

Adding Bank Card

Sample request

curl --location 
  --request POST 'https://my.solarstaff.com/api/customer/freelancers/cards' \
  --data-raw '{
        "code": 583695,
        "freelancerId": 1
    }'

Sample response

HTTP status 200 OK

{
  "redirect": "https://link-to-payment-terminal",
  "uuid": "425fcc9b-df96-4f15-85fe-f3e259be7442"
}

This request is used to add a new payment method for a freelancer. It returns a link to the page for adding a payment method. Before calling the request, you also need to request a code that will be sent to the freelancer's phone number. Adding a new payment method is done as follows:

  • Request a code to be sent to the freelancer's phone.
  • Call the request to add a payment method by passing the code sent in the previous step as the input parameter. Next, the request returns a link to the page where the freelancer can enter payment method details. After that, the freelancer fills in the details of a new payment method.

Request

HTTP Request
Request body
Name Type Required Description
code integer Yes Code sent to the freelancer's phone number
freelancerId integer Either freelancerId or freelancerUuid is required Freelancer ID
freelancerUuid string Either freelancerId or freelancerUuid is required Freelancer UUID (for example, 8e947213-c114-41ec-a9ae-0242ac130002)
redirectUrl integer No URL where the freelancer is redirected after linking a payment method

Response

Property Name Type Description
redirect string URL of the page for adding a payment method
uuid string Payment method UUID (for example, 8e947213-c114-41ec-a9ae-0242ac130002)

Adding Bank Account

Sample request

curl --location 
  --request POST 'https://my.solarstaff.com/api/customer/freelancers/bank-accounts' \
  --data-raw '{
        "code": 583695,
        "freelancerId": 1
    }'

Sample response

HTTP status 200 OK

{
  "redirect": "https://link-to-payment-terminal",
    "uuid": "425fcc9b-df96-4f15-85fe-f3e259be7442"
}

This request is used to add a new bank account for a freelancer. It returns a link to the page for adding a payment method. Before calling the request, you also need to request a code that will be sent to the freelancer's phone number. Adding a new bank account is done as follows:

  • Request a code to be sent to the freelancer's phone.
  • Call the request to add a payment method by passing the code sent in the previous step as the input parameter. Next, the request returns a link to the page where the freelancer can enter payment method details. After that, the freelancer fills in the details of a new payment method.

Request

HTTP Request
Request body
Name Type Required Description
code integer Yes Code sent to the freelancer's phone number
freelancerId integer Either freelancerId or freelancerUuid is required Freelancer ID
freelancerUuid string Either freelancerId or freelancerUuid is required Freelancer UUID (for example, 8e947213-c114-41ec-a9ae-0242ac130002)
bankAccountType integer Yes Bank account type. Possible values:
  • 1: Account in a eurozone country (SEPA)
  • 2: SWIFT account
  • 6: Russian bank account (BIC)
redirectUrl integer No URL where the freelancer is redirected after linking a payment method
uuid string Payment method UUID (for example, 8e947213-c114-41ec-a9ae-0242ac130002)

Response

Property Name Type Description
redirect string URL of the page for adding a payment method

Adding E-wallet

Sample request

curl --location 
  --request POST 'https://my.solarstaff.com/api/customer/freelancers/wallets' \
  --data-raw '{
        "code": 583695,
        "freelancerId": 1
    }'

Sample response

HTTP status 200 OK

{
  "redirect": "https://link-to-payment-terminal",
    "uuid": "425fcc9b-df96-4f15-85fe-f3e259be7442"
}

This request is used to add a new e-wallet for the freelancer. It returns a link to the page for adding a payment method. Before calling the request, you also need to request a code that will be sent to the freelancer's phone number. Adding a new bank account is done as follows:

  • Request a code to be sent to the freelancer's phone.
  • Call the request to add a payment method by passing the code sent in the previous step as the input parameter. Next, the request returns a link to the page where the freelancer can enter payment method details. After that, the freelancer fills in the details of a new payment method.

Request

HTTP Request
Request body
Name Type Required Description
code integer Yes Code sent to the freelancer's phone number
freelancerId integer Either freelancerId or freelancerUuid is required Freelancer ID
freelancerUuid string Either freelancerId or freelancerUuid is required Freelancer UUID (for example, 8e947213-c114-41ec-a9ae-0242ac130002)
walletType integer Yes E-wallet type. Possible values:
  • 3: WebMoney
redirectUrl integer No URL where the freelancer is redirected after linking a payment method

Response

Property Name Type Description
redirect string URL of the page for adding a payment method
uuid string Payment method UUID (for example, 8e947213-c114-41ec-a9ae-0242ac130002)

Deleting Bank Card

Sample request

curl --location 
  --request DELETE 'https://my.solarstaff.com/api/customer/freelancers/cards/123?freelancerId=123' \

Sample response

HTTP status 200 OK

This request is used to delete a bank card.

Request

HTTP Request
Path-parameters

As a path parameter, you must pass bank card ID.

Query parameters
Name Type Required Description
freelancerId or freelancerUuid integer Yes Freelancer ID or UUID

Response

A successful request returns an empty response.

Deleting E-wallet

Sample request

curl --location 
  --request DELETE 'https://my.solarstaff.com/api/customer/freelancers/wallets/123?freelancerId=123' \

Sample response

HTTP status 200 OK

This request is used to delete a freelancer's e-wallet.

Запрос

HTTP запрос
Path-parameters

As a path parameter, you must pass e-wallet ID.

Query parameters
Name Type Required Description
freelancerId or freelancerUuid integer Yes Freelancer ID or UUID

Response

A successful request returns an empty response.

Deleting Bank Account

Sample request

curl --location 
  --request DELETE 'https://my.solarstaff.com/api/customer/freelancers/bank-accounts/123?freelancerId=123' \

Sample response

HTTP status 200 OK

This request is used to delete a freelancer's bank account.

Request

HTTP Request
Path-parameters

As a path parameter, you must pass bank account ID.

Query parameters
Name Type Required Description
freelancerId or freelancerUuid integer Yes Freelancer ID or UUID

Ответ

A successful request returns an empty response.

Requesting Code for Adding New Payment Method

Sample request

curl --location 
  --request POST 'https://my.solarstaff.com/api/customer/freelancers/request-code-for-new-payout-endpoint' \
  --data-raw '{
        "freelancerId": 583695
    }'

Sample response

HTTP status 200 OK

{
  "type": "SMS",
  "number": "412341"
}

This request is used to send a verification code to the freelancer's phone number. To add a new payment method, the freelancer must confirm the action.

Request

HTTP Request
Request body
Name Type Required Description
freelancerId integer Either freelancerId or freelancerUuid is required Freelancer ID
freelancerUuid string Either freelancerId or freelancerUuid is required Freelancer UUID (for example, 8e947213-c114-41ec-a9ae-0242ac130002)

Response

Property Name Type Description
type string Message type (SMS or Google)
number string Freelancer's phone number (if the message type is SMS)

Company

This section details methods used for managing a company.

Retrieving User's Companies

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/companies" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."

Sample response

HTTP status code: 200 OK

{
  "items": [
    {
      "id": 2955,
      "companyName": "Цвет",
      "brandName": "Цвет",
      "safeDealEnabled": true,
      "isDefault": true,
      "currency": {
        "currency": "RUB",
        "id": 1
      }
    }
  ],
  "pagination": {
    "count": 1,
    "total": 1,
    "perPage": 20,
    "page": 1,
    "pages": 1
  }
}

This request is used to retrive the companies of an authorized user.

Request

HTTP Request
Parameters

There are no additional request parameters.

Response

Property Name Type Description
id integer Company ID
companyName string Company name
brandName string Project name
safeDealEnabled boolean Indicates whether the Secure Deal feature is enabled
isDefault boolean Indicates whether this is the default company
currency object Currency
currency.currency string Currency name
currency.id integer Currency ID

Changing Company

Sample request

curl -X PATCH "https://my.solarstaff.com/api/customer/companies" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -d "{
        "companyId": 123
      }"

Sample response

HTTP status code: 200 OK

{
  "token": "eyJhbGciOiJIUzUxMiIsI...",
  "refreshToken": "c84f18a2-c6c7-4850-be15-93f9cbaef3b3"
}

This request is used to select a company: if you have added several companies to your account, this is the way you select one of them. The request returns a new JWT that is to be used for authenticating all requests that follow.

Request

HTTP Request
Request body
Parameter Type Required Description
companyId integer Yes Company ID. The list of companies that are available to you is returned with this request

Ответ

Property Name Type Description
token string JWT
refreshToken string JWT used for token update

Retrieving Company Balance

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/balance 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."

Sample response

HTTP status code: 200 OK

{
  "currency": {
    "currency": "RUB",
    "id": 1
  },
  "showVat": true,
  "balanceAmount": 1067273.53,
  "balanceAmountVat": 213454.71,
  "holdAmount": 149225.08,
  "holdAmountVat": 29845.02
}

This request is used to retrieve the company's balance.

Request

HTTP Request
Parameters

There are no additional request parameters.

Ответ

Property Name Type Description
currency object Currency
currency.currency string Currency name
currency.id integer Currency ID
showVat boolean Indicates whether VAT is displayed within tasks
balanceAmount string Balance
balanceAmountVat string VAT on the balance
holdAmount string Held (escrowed) amount
holdAmountVat string Held (escrowed) VAT amount

Documents

This section details methods used for managing documents.

Retrieving Document List

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/documents" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status code: 200 OK

{
  "items": [
    {
      "fileId": 252345,
      "type": 6,
      "documentId": 10743,
      "invoiceStatusId": 1,
      "reportStatusId": null,
      "amount": 100,
      "number": "2955-211126-18",
      "currency": {
        "currency": "RUB",
        "id": 1
      },
      "createdAt": "2021-11-26 04:54:39",
      "topUpBalanceDate": "-0001-11-30 00:00:00",
      "sfFileId": null
    }
}

This request is used to retrive a list of documents.

Request

HTTP Request
Query parameters
Parameter Type Required Description
filter[type] integer No Document type. Possible values:
  • 6: Invoice
  • 7: Certificate
filter[dateFrom] date No Document's "effective from" date (start of interval)
filter[dateTo] date No Document's "effective until" date (end of interval)
sort string No Parameter for sorting results. Possible values:
  • createdAt: Date of document creation
  • id: Document ID
  • fileId: File ID
direction string No Sort order. Possible values:
  • asc: Regular (ascending) sort order
  • desc: Reverse (descending) sort order

Ответ

Property Name Type Description
fileId integer File ID
type integer Document type. Possible values:
  • 6: Invoice
  • 7: Certificate
documentId integer Document ID
invoiceStatusId integer Invoice status ID
reportStatusId integer Certificate status ID
amount string Document amount
number string Document number
currency object Currency
currency.currency string Currency name
currency.id string Currency ID
createdAt string Date of document generation
topUpBalanceDate string Balance top-up date
sfFileId boolean Invoice ID (applies to invoices generated for balance funding operations)

Downloading Documents

Sample request

curl -X GET "https://my.solarstaff.com/api/customer/documents/download" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status code: 200 OK

A successful request returns an empty response.

This request is used to download documents. After the request is called, a document download link is sent to your email.

Request

HTTP Request
Query parameters
Parameter Type Required Description
filter[type] integer No Document type. Possible values:
  • 6: Invoice
  • 7: Certificate
filter[dateFrom] date No Document's "effective from" date (start of interval)
filter[dateTo] date No Document's "effective until" date (end of interval)

Response

A successful request returns an empty response, initiating the sending of an email that contains a link for document download (in ZIP format).

User Profile 

The section lists the requests for working with the user profile:

Personal Details

Retrieving Personal Details

Sample request

curl -X GET "https://my.solarstaff.com/api/profile" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 

Sample response

HTTP status 200 OK

{
  "languageStringValue": "RU",
  "name": "Ivanov Ivan",
  "postCode": "123123",
  "physicalAddress": "Moscow, Lenina 23",
  "city": "Moscow",
  "inn": "123123123",
  "ip": "10.244.1.113",
  "birthDate": "11.03.2000",
  "gridsSettings": "{\"freelancers_table_column\":[\"expander\",\"date\",\"regDate\",\"email\",\"category\",\"freelancer\",\"notes\",\"paysystems\",\"invitationStatus\",\"freelancer_registered\",\"taxation_status_id\",\"freelancer_is_verified\",\"actions\"],\"ftasks_pageSize\":100,\"columns_ftasks\":[\"checkbox\",\"actions\",\"id\",\"merchant_txid\",\"creator_name\",\"payer_name\",\"worker_name\",\"worker_email\",\"taxation_status\",\"id_uploaded\",\"note\",\"groups\",\"task_title\",\"description\",\"task_caption\",\"task_attributes\",\"date_create\",\"price\",\"price_to_pay\",\"price_with_vat\",\"currency\",\"date\",\"date_end\",\"date_finished\",\"date_paid\",\"reports\",\"intellectual_property\",\"status\",\"deadline\"]}",
  "loginNotification": true,
  "id": 100,
  "uuid": "2b69eb5d-e0e3-11ec-95b5-fa84c4fedfee",
  "email": "[email protected]",
  "username": "[email protected]",
  "firstName": "Иван",
  "middleName": "",
  "lastName": "Иванов",
  "regDate": "2020-10-30",
  "twoFaMethod": "sms",
  "taxationStatus": 1,
  "phone": "44454545",
  "country": "RU",
  "state": null,
  "flags": 0,
  "type": "customer",
  "defaultSmsGate": null,
  "language": "RU",
  "isVerified": false,
  "specialization": null
}

This method is used to retrieve the personal details of an authorized user.

Request

HTTP Request
Parameters

There are no additional request parameters. Only applicable for authorized users.

Response

Name Type Description
postCode string User's postal code
physicalAddress string User's address
city string City
inn string INN (taxpayer ID, applicable for users in Russia)
ip string Allowed IP addresses
birthDate string Date of birth
gridsSettings object [System field] Account interface settings
id integer User ID
email string User's email
username string User's login
firstName string Username
middleName string User's middle name
lastName string User's last name
regDate string Registration date
twoFaMethod boolean Indicates whether two-factor authentication is enabled
taxationStatus string User's tax status (applies to freelancers only)
phone string User's phone number
country string User's country
state string User's region
flags string [System field]
type string [System field] User type (client or freelancer)
language string User's interface language
isVerified string Indicates whether the user is verified (applies to freelancers only)

Account Settings

Changing Language

Sample request

curl -X PUT "https://my.solarstaff.com/api/profile/language" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
          "language": "RU"
        }"

Sample response

HTTP status 200 OK

A successful request should return an empty response.

This method is used to change the language for all messages, task categories, and so on. The available options are Russian (RU) and English (EN).

Request

HTTP Request
Request body
Name Type Обязательность Description
language string Yes Language name. Possible options: 
  • EN: English
  • RU: Russian

Response

A successful request should return an empty response.

Reference

This section lists requests for retrieving various values of different parameters (for example, currencies, deadline types, and tax statuses).

Currency List

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/lookups/currencies' \

Sample response

HTTP status 200 OK

{
  "RUB": 1,
  "USD": 2,
  "EUR": 3
}

This method is used to retrieve a list of currencies and their IDs.

Request

HTTP Request
Parameters

There are no additional request parameters.

Response

Name Type Description
<код валюты> integer Currency ID

Currency Conversion Rate

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/exchanges' \

Sample response

HTTP status 200 OK

[
  {
    "base": {
      "currency": "EUR",
      "id": 3
    },
    "target": {
      "currency": "RUB",
      "id": 1
    },
    "rate": 79.401
  },
  {
    "base": {
      "currency": "USD",
      "id": 2
    },
    "target": {
      "currency": "RUB",
      "id": 1
    },
    "rate": 74.329
  },
  {
    "base": {
      "currency": "EUR",
      "id": 3
    },
    "target": {
      "currency": "USD",
      "id": 2
    },
    "rate": 1.0576
  },
  {
    "base": {
      "currency": "RUB",
      "id": 1
    },
    "target": {
      "currency": "EUR",
      "id": 3
    },
    "rate": 81.8194
  },
  {
    "base": {
      "currency": "RUB",
      "id": 1
    },
    "target": {
      "currency": "USD",
      "id": 2
    },
    "rate": 76.5928
  },
  {
    "base": {
      "currency": "USD",
      "id": 2
    },
    "target": {
      "currency": "EUR",
      "id": 3
    },
    "rate": 1.0898
  }
]

This method is used to retrieve the current conversion rate.

Sample conversions:

Withdrawal currency Payout currency Conversion rate Calculation
EUR RUB 79.401 1000 EUR * 79.401 = 79401 RUB
USD RUB 74.329 1000 USD * 74.329 = 74329 RUB
EUR USD 1.0576 1000 EUR * 1.0576 = 1057.6 USD
RUB EUR 81.8194 1000 RUB / 81.8194 = 12.23 EUR
RUB USD 76.5928 1000 RUB / 76.5928 = 13.06 USD
USD EUR 1.0898 1000 USD / 1.0898 = 917.43 EUR

Request

HTTP Request
Parameters

There are no additional request parameters.

Response

Name Type Description
base.currency string Name of the base currency to be converted
base.id integer Base currency ID
target.currency string ID of the target currency of conversion
target.id integer ID of the target currency of conversion
rate integer Conversion rate

Task Deadlines

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/lookups/deadlines' \

Sample response

HTTP status 200 OK

{
  "SOFT": 1,
  "HARD": 2
}

This method is used to retrieve deadlines and their IDs.

Request

HTTP Request
Parameters

There are no additional request parameters.

Response

Name Type Description
<Deadline type> integer Deadline ID

Tax Statuses

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/lookups/taxation-statuses' \

Sample response

HTTP status 200 OK

{
  "NATURAL": 1,
  "NATURAL_TITLE": "Natural person",
  "SELF_EMPLOYED": 3,
  "SELF_EMPLOYED_TITLE": "Self employed person",
  "SOLE_PROPRIETOR": 4,
  "SOLE_PROPRIETOR_TITLE": "Individual entrepreneur"
}

This method is used to retrieve tax statuses and their IDs.

Request

HTTP Request
Parameters

Дополнительных параметров запроса нет.

Response

Name Type Description
<Tax status> integer Tax status ID
<Tax status>_TITLE string Name of tax status

Task Categories

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/customer/lookups/categories' \

Sample response

HTTP status 200 OK

{
  "items": [
    {
      "id": 1,
      "title": "Печатные СМИ",
      "titleEn": "Printed mass media"
    },
    {
      "id": 2,
      "title": "Интернет-реклама",
      "titleEn": "Internet advertising"
    }
  ]
}

This method is used to retrieve task categories.

Request

HTTP Request
Parameters

There are no additional request parameters.

Response

Name Type Description
id integer Category ID
title string Task category name
titleEn string Task category name (in English)

Names of Services and Works

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/lookups/services/1' \

Sample response

HTTP status 200 OK

{
  "items": [
    {
      "id": 3,
      "title": "Копирайтинг",
      "titleEn": "Copywriting",
      "titleDoc": "Написание текстов статей/обзоров",
      "titleDocEn": "Сopywriting of texts of articles/reviews"
    },
    {
      "id": 2,
      "title": "Работы по созданию иллюстраций к текстам (включая фотографию)",
      "titleEn": "Work on creation of illustrations for  texts (incl. photos)",
      "titleDoc": "Работы по созданию иллюстраций (включая фотографические) к текстам статей периодического СМИ",
      "titleDocEn": "Work on creation of illustrations (incl. photos) for  texts of articles of periodic mass media"
    }
  ]
   "pagination": {
    "count": 20,
    "total": 23,
    "perPage": 9999,
    "page": 1,
    "pages": 1
  }
}

This method is used to retrieve the names of the services and works for the requested task category.

Request

HTTP Request
Path-parameters

As a path parameter, you must pass task category ID.

Parameters
Name Type Description
page integer No Page number for page output
size integer No Number of items per page (20 by default, 500 maximum)

Response

Name Type Description
id integer ID of services and/or works
title string Name of services and/or works
titleEn string Name of services and/or works (in English)
titleDoc string Name of services and/or works as stated in the certificate
titleDocEn string Name of services and/or works as stated in the certificate (in English)
pagination list Paginated output
pagination.count integer Number of items returned
pagination.total integer Total items available with the requested filter
pagination.perPage integer Number of items per page
pagination.page integer Page number
pagination.pages integer Total pages

Task Attributes

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/lookups/service-attributes/1' \

Sample response

HTTP status 200 OK

{
  "items": [
    {
      "id": 6,
      "title": "Наименование СМИ",
      "titleEn": "Name of mass media",
      "type": "text"
    },
    {
      "id": 9,
      "title": "Номер издания",
      "titleEn": "Issue",
      "type": "text"
    },
    {
    "id": 31,
    "title": "Формат видео",
    "titleEn": "Video format",
    "type": "select",
    "attrTypeId": 11,
    "options": [
      {
        "id": 26,
        "value": "SD",
        "valueEn": "SD"
      },
      {
        "id": 27,
        "value": "HD",
        "valueEn": "HD"
      },
      {
        "id": 29,
        "value": "FullHD",
        "valueEn": "FullHD"
      },
      {
        "id": 28,
        "value": "UHD",
        "valueEn": "UHD"
      },
      {
        "id": 30,
        "value": "4K",
        "valueEn": "4K"
      }
    ]
  },
  ],
 "pagination": {
    "count": 20,
    "total": 23,
    "perPage": 9999,
    "page": 1,
    "pages": 1
  }
}

This method is used to retrieve the attributes for the requested task category.

Path-parameters

As a path parameter, you must pass task category ID.

Request

HTTP Request
Parameters
Name Type Required Description
id integer Yes Service ID
page integer No Page number for page output
size integer No Number of items per page (20 by default, 500 maximum)

Response

Name Type Description
items list List items
items.id integer Attribute ID
items.title string Attribute name
items.titleEn string Attribute name (in English)
items.attrTypeId integer Attribute type ID
options object Attribute values (for the "select" type)
options.id integer Value ID
options.value string Text
options.valueEn string Text in English
pagination list Paginated output
pagination.count integer Number of items returned
pagination.total integer Total items available with the requested filter
pagination.perPage integer Number of items per page
pagination.page integer Page number
pagination.pages integer Total pages

Additional Documents for Task Acceptance

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/customer/lookups/acceptance-files' \

Sample response

HTTP status 200 OK

{
  "items": [
    {
      "id": 1049,
      "fileId": 123,
      "title": "Соглашение о неразглашении (NDA)",
      "titleEn": "Non-disclosure agreement"
    }
  ]
}

This method is used to retrieve a list of documents that a freelancer must accept before working on tasks. These include NDAs and other docs. To upload a document like that to the service, please contact support.

Request

HTTP Request
Parameters

There are no additional request parameters.

Response

Name Type Description
id integer Document ID
fileId integer Document file ID
title string Document name
titleEn string Document name (in English)

Freelancer specializations

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/lookups/specializations' \

Sample response

HTTP status 200 OK

[
{
      "id": 1,
      "title": "Бухгалтер",
      "titleEn": "Accountant",
},
{
"id": 158,
"title": "Актер",
"titleEn": "Actor",
}
]

The method is used to retrieve specializations for the freelancer.

Request

HTTP Request
Parameters

There are no additional request parameters.

Response

Name Type Description
id integer Specialization ID
title string Specialization name
titleEn string Specialization name (in English)

Country Codes

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/customer/ord/get-arccw-codes' \

Sample response

HTTP status 200 OK

{
  "items": [
    {
      "id": 1049,
      "title": "Латвия"
    }
  ]
}

This method is used to retrieve a list of countries and their identifiers from the Russian Classification of the World's Countries (OKSM).

Request

HTTP Request
Parameters

There are no additional request parameters.

Response

Name Type Description
id integer Country ID
title string Country name

WebHooks

Webhooks are messages that notify services about events within Solar Staff. You can add a custom URL where all event notifications will be sent. Use this request to add such a URL. After that, you can set it up in a way where only the necessary received events are processed. Solar Staff always sends all event notifications to the URL you added, and you can then filter those events as you wish (the name field will help you determine event type).

Available events:

  • Freelancer registration. If you working using the API, freelancers need to complete sign-up on their own. You can set up a webhook notifying you about freelancers following the email link and filling out the sign-up form.
  • Adding/deleting a payment method. Adding a payment method is also something freelancers do on their own, so you can set up the respective notification.
  • Changing the tax status of the contractor.
  • Enabling or disabling auto tax payment for individuals in Russia.

Sample message that is sent to the specified URL:

{  
  "timestamp": 1674539549,
  "name": "cardAdded",
  "payload": {
    "ownerId": 6,
    "id": 11
  }
}

Parameters:

  • name - Event name,
  • payload - Event data. Possible values include:
    • Notifying about a payment method being added returns the parameters ownerId (ID of the user that added the method) and ID (ID of the payment method)
    • For freelancer registration, the uuid of the freelancer is returned.
    • Changing the tax status of the contractor (only applicable for freelancers from the Russian Federation) returns the uuid of the freelancer and their tax status.
    • For automatic tax payments for individuals, the uuid of the freelancer is returned along with a boolean indicating whether the automatic payment is enabled (true) or disabled (false).
  • timestamp - Event date

Each request carries a special X-Sign header with a signature. The signature appears as sha256(body . secret), where:

  • secret - is a secret key from the GET api/v1/customer/web-hook request.
  • body - is the request body.

If you have several companies, setting up a webhook for each requires going to a company and calling a request to create a webhook.

If the client is not responding (or responds with an HTTP code other than 200), Solar Staff will keep attempting to send the notification for the next 24 hours.

Retrieve Webhook

Sample request

curl --location 
  --request GET 'https://my.solarstaff.com/api/customer/web-hook' \

Sample response

HTTP status 200 OK

{
  "url": "https://webhook.site/588190fc-47d6-47f2-bded-17216bfe6e92",
  "status": "enabled",
  "secret": "bb940556f36a5ae58063f151e51f5318",
  "lastTriggered": null,
  "lastError": null
}

This method is used to retrieve webhook details.

Request

HTTP Request

Parameters

No additional parameters.

Response

Name Type Description
url string Target URL for notifications
status string Status. Available options:
  • enabled: Enabled
  • disabled: Disabled
secret string Secret key to be included in each notification
lastTriggered string Indicates when the last notification was sent
lastError string Indicates when the last notification failed to arrive

Create or Update Webhook

Sample request

curl --location 
  --request POST 'https://my.solarstaff.com/api/customer/web-hook' \
  --data-raw '{
        "status" : "enabled",
        "url" : "https://test.com"
    }'

Sample response

HTTP status 200 OK

This method is used to add or update a webhook. In other words, you are adding a URL where all events (such as the adding or removing of a freelancer's payment method) are to be sent. To enable or disable the sending of event notifications, pass enabled or disabled respectively in status.

Request

HTTP Request

Parameters

Name Type Обязательность Description
status string Yes Status. Available options:
  • enabled: Enabled
  • disabled : Disabled
url string Yes Target URL for notifications

Response

A successful request returns an empty response.

Delete Webhook

Sample request

curl --location 
  --request DELETE 'https://my.solarstaff.com/api/customer/web-hook' \
  --data-raw '{
        "status" : "enabled",
        "url" : "https://test.com"
    }'

Sample response

HTTP status 200 OK

This method is used to delete webhooks.

Request

HTTP Request

Parameters

No additional parameters.

Response

A successful request returns an empty response.

Postman Request Collection

The Solar Staff API supports pre-built Postman request collections. These collections come with brief instructions on using variables and sending requests in Postman.

To use a Postman request collection:

Step 1

Open a Postman request collection.


Step 2

Click Fork Collection to copy the request collection to your Postman workspace.

In the window that opens, provide the name of the collection copy and of the workspace where that copy is to be created. Check "Watch original collection" if you want to be notified of changes to the original request collection.

Enter a name and select a workspace.

Step 3

Go to the token request and provide your authorization details.

Step 4

Go to the collection settings -> Authorization and copy the received token.

Release notes

August 2024

Added:

  • Added the shareCommission parameter to the tasks request, replacing compensateWorkerServiceFee. This new parameter allows you to share 1% of the commission with the freelancer

June 2024

Added:

April 2024

Added:

  • New events for webhooks: freelancer registration, changes to a freelancer's tax status, and enabling/disabling automatic tax payments.
  • A parameter for compensating the freelancer's commission compensationType has been added to the task creation request. The parameter determines the type of payment method the freelancer will use to withdraw funds. Since the commission percentage varies for different payment methods, this parameter enables the precise calculation of the freelancer's commission percentage.
  • In the response to the payment method addition request, a UUID parameter for the payment method has been included.
  • Upon retrieving the list of payment methods, a parameter is now included that shows whether auto-payment has been enabled for each payment method.

November 2023

A parameter fileId has been added to the response of the request to get a list of documents for accepting a task.

A parameter for compensating the freelancer's commission compensateWorkerServiceFee has been added to the task creation request .

October 2023

The task payment creation request now allows for specifying a currency in which the conversion should be performed before withdrawing the funds.

August 2023

Added:

July 2023

Added: