NAV Navbar
Mellow

Overview

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

General Information

The Mellow 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.

The 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.

For developers' convenience, Mellow provides a sandbox to test things out before deploying to production. To make use of the sandbox, contact the Mellow 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.mellow.io/api

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

Authentication and Authorization

Authentication is performed using JSON Web Tokens. 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

Sample request

curl --location \
    --request POST 'https://my.mellow.io/api/login' \
    --data-raw '{
        "username": "Ivan",
        "password": "123123",
        "code": 0
    }'

Sample response If the code parameter was passed correctly or the user does not have two-factor authentication enabled:

HTTP status 200 OK

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

If the code parameter was not passed and the user has two-factor authentication enabled:

HTTP status 200 OK

{
    "2FA": {
        "type": "SMS" | "Google",
        "number": "+8279823472"
    }
}

This request allows you to obtain a JWT, which is used for authenticating all other requests.

Request

HTTP Request

https://my.mellow.io/api/login

Parameters
Parameter Name Type Required Description
username string Yes Username
password string Yes Password
code string No Two-factor authentication 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, valid for 65 days

JWT Update

Sample request

curl --location \
    --request POST 'https://my.mellow.io/api/token/refresh' \
    --data-raw '{
        "refreshToken": "c84f18a2-c6c7-4850-be15-93f9cbaef3b3"
    }'

Sample response

HTTP status 200 OK

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

This request allows you to obtain an updated JWT, which is used for authenticating all other requests.

Request

HTTP Request

https://my.mellow.io/api/token/refresh

Parameters
Parameter Name Type Required Description
refreshToken string Yes JWT token

Response

Property Name Type Description
token string JWT token
refreshToken string JWT token used for token update, valid for 65 days

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 Mellow API and contains instructions for the most common actions in the system:

Quickstart

Before You Begin

Authentication

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.mellow.io/api/login

Note: For the test environment, use:
POST https://demo.mellow.io/api/login

The JWT you receive has a lifespan of 65 days. After this period, you will need to generate a new token by repeating the authentication process. The token must 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:

If your freelancers are going to sign up for and use Mellow, 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 Mellow 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.
  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.mellow.io/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.mellow.io/api/tasks

A successful request returns an empty response with code 200.

Changing Task Statuses

The stages of a task are as follows:

When using the API, you need to have these stages performed sequentially. Paying for a task is done via a separate request (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:

The request's method and URI: PUT https://my.mellow.io/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.mellow.io/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 Mellow (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 created Customer
In progress ID=2 Freelancer has accepted the task to work on it Freelancer
Pending review ID=3 Freelancer has completed the task, and it is awaiting customer review Freelancer
Pending payment ID=4 Task accepted by customer and is awaiting payment Customer
Completed ID=5 Task has been paid for Customer
Rejected by freelancer ID=6 Freelancer has rejected the task Freelancer
Rejected by customer ID=8 Customer has rejected the task completed by the freelancer Customer
Awaiting freelancer’s confirmation of cancellation ID=11 Customer has rejected the task, pending freelancer’s confirmation of cancellation Customer
Queued for payment ID=12 Customer has initiated payment, but payment is still in process. Once processed, the task status will automatically change to Completed (ID=5). If the task remains in this status for too long, please contact support Customer
Dispute initiated ID=13 Freelancer has clicked Dispute Task and is awaiting a response from the customer Freelancer
Customer review required ID=14 If the freelancer did not complete the task by the deadline, the customer must choose whether to extend the deadline or cancel the task Automatically upon reaching the deadline
Changes under review ID=16 Customer has proposed changes to task parameters and is awaiting freelancer’s response Customer

Task Management

This section includes requests for retrieving, creating tasks, and changing task status.

Retrieving Task List

Sample request

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

Sample response

HTTP status code: 200 OK

{
  "items": [
    {
      "additionalAttributes": null,
      "category": {
        "id": 20,
        "title": "Управление размещением медийной рекламы",
        "titleEn": "ATL advertising management",
        "titleDoc": "Услуги по управлению размещением рекламных материалов  на интернет сайтах",
        "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": "Olimp LLC"
      },
      "creator": {
        "id": 100740,
        "fullName": "Ivan Petrov"
      },
      "worker": {
        "id": 100871,
        "email": "[email protected]",
        "firstName": "Nina",
        "lastName": "Malina",
        "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": "Task related to social media analysis",
      "uuid": "123e4567-e89b-12d3-a456-426655440000",
      "files": [
        {
          "id": 252479,
          "name": "analysis_report.pdf",
          "typeId": 5,
          "ownerId": 100556
        }
      ],
      "id": 583689,
      "needReport": false,
      "price": 150,
      "state": 5,
      "title": "Freelancer Thailand Project",
      "deadline": {
        "type": 0,
        "triggerDate": null,
        "isComingUp": false
      },
      "hold": {
        "type": "without_hold",
        "isActive": false
      },
      "insurance": {
        "status": 0
      },
      "group": {
        "id": 654,
        "title": "Market Analysis Group"
      },
      "messageCount": 0,
      "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
Parameters
Parameter Type Required Description
filter[creatorId] integer No ID of the user who created the task
filter[workerId] integer No Contractor ID. To retrieve a list of freelancers, use this request
filter[companyId] integer No Company ID. For a list of companies, refer to this request
filter[dateCreatedFrom] string No Task creation date (start of range). Format: YYYY-MM-DD (e.g., 2020-09-03), with time defaulting to 00:00:00
filter[dateCreatedTo] string No Task creation date (end of range). Format: YYYY-MM-DD (e.g., 2020-09-03), with time defaulting to 23:59:59
filter[dateEndFrom] string No Task deadline (start of range). Format: YYYY-MM-DD (e.g., 2020-09-03), with time defaulting to 00:00:00
filter[dateEndTo] string No Task deadline (end of range). Format: YYYY-MM-DD (e.g., 2020-09-03), with time defaulting to 23:59:59
filter[dateFinishedFrom] string No Task completion date (start of range). Format: YYYY-MM-DD (e.g., 2020-09-03), with time defaulting to 00:00:00
filter[dateFinishedTo] string No Task completion date (end of range). Format: YYYY-MM-DD (e.g., 2020-09-03), with time defaulting to 23:59:59
filter[dateReportFrom] string No Certificate generation date (start of range). Format: YYYY-MM-DD (e.g., 2020-09-03), with time defaulting to 00:00:00
filter[dateReportTo] string No Certificate generation date (end of range). Format: YYYY-MM-DD (e.g., 2020-09-03), with time defaulting to 23:59:59
filter[dateAcceptedFrom] string No Date when the client accepts the task (start of range). Format: YYYY-MM-DD (e.g., 2020-09-03), with time defaulting to 00:00:00
filter[dateAcceptedTo] string No Date when the client accepts the task (end of range). Format: YYYY-MM-DD (e.g., 2020-09-03), with time defaulting to 23:59:59
filter[datePaidFrom] string No Task payment date (start of range). Format: YYYY-MM-DD (e.g., 2020-09-03), with time defaulting to 00:00:00
filter[datePaidTo] string No Task payment date (end of range). Format: YYYY-MM-DD (e.g., 2020-09-03), with time defaulting to 23:59:59
filter[hasPayout] boolean No Indicator for returning only paid tasks. Value 0 returns tasks without payouts (see here 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] array of integers No Task status. You can pass one or multiple 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
filter[externalId] string No External task ID that can be set when creating a task (merchant_txid)
sort string No Attribute 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 pagination
size integer No Number of items per page (default is 20, maximum is 500)
Response

A successful request returns the following response:

Property Type Description
items list List of items
id integer Task ID
additionalAttributes object Additional task attributes
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 Parent task category
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 percentage
copyright string Intellectual property rights transfer indicator
createType string Task creation method (via 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 Task creator
creator.id integer Creator user ID
creator.fullName string Full name of the creator
worker object Freelancer
worker.id integer Freelancer ID (returned in freelancer retrieval request)
worker.email string Freelancer email
worker.firstName string Freelancer first name
worker.lastName string Freelancer last name
worker.isVerified boolean Verification status of the freelancer
dateCreated string Task creation date
dateAccepted string Date the task was accepted by the client
dateEnd string Task deadline
dateFinished string Task completion date
datePaid string Task payment date
datePayAt string Task payment initiation date
documentDate string Accounting document generation date
description string Task description
uuid uuid Task UUID
needReport boolean Indicates if a report is required for the task
price float Task price
state integer Task status
title string Task name
hasPayout boolean Indicates if a payout is present for the task
files object Attached files
files.id string File ID
files.name string Filename
files.typeId string File type
files.ownerId string ID of the file's uploader (files can be added by both clients and freelancers)
deadline object Deadline
deadline.type integer Deadline type (soft 1 or hard 2)
deadline.triggerDate string Deadline date
deadline.isComingUp boolean Indicates if 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 Fund holding (escrow)
hold.type string Holding (escrow) type
hold.isActive boolean Indicates if fund holding is active for the task
insurance object Insurance
insurance.status integer Insurance status
messageCount integer Number of messages
activeDispute boolean Indicates if there is an open dispute
activeChangesetId integer Indicates if change approval is ongoing for the task
issueCode string Task processing error (e.g., insufficient funds for holding if Secure Deal is enabled)
compensateWorkerServiceFee boolean Freelancer service fee compensation indicator (if true, the client covers the freelancer's fee)
pagination list Paginated output of items
pagination.count integer Number of returned items
pagination.total integer Total items available for 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.mellow.io/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": "Andrey Smirnov"
  },
  "worker": {
    "id": 100871,
    "email": "[email protected]",
    "firstName": "Nina",
    "lastName": "Malina",
    "isVerified": true
  },
  "files": [],
  "links": [],
  "messageCount": 0,
  "additionalAttributes": null,
  "category": {
    "id": 20,
    "title": "Управление размещением медийной рекламы",
    "titleEn": "ATL advertising management",
    "titleDoc": "Услуги по управлению размещением рекламных материалов  на интернет сайтах",
    "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": 3021,
    "title": "OOO Tekhnoprom"
  },
  "dateCreated": "2021-09-15 09:45:00",
  "dateAccepted": "2021-09-15 12:00:00",
  "dateEnd": "2021-09-20 18:00:00",
  "dateFinished": null,
  "datePaid": "2021-09-20 18:30:00",
  "datePayAt": null,
  "documentDate": "2021-09-20 18:00:00",
  "description": "Website development task",
  "uuid": "987e1234-a89b-56d3-b123-427677440000",
  "id": 584123,
  "needReport": true,
  "price": 250,
  "state": 3,
  "title": "WebDev Singapore Project",
  "deadline": {
    "type": 0,
    "triggerDate": null,
    "isComingUp": false
  },
  "hold": {
    "type": "without_hold",
    "isActive": false
  },
  "insurance": {
    "status": 0
  },
  "activeDispute": null,
  "activeChangesetId": null
}

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
id integer Task ID
additionalAttributes object Additional task attributes
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 Parent task category
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 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
needReport boolean Indicates whether a task report is required
description string Task description
uuid uuid Task's UUID
price float Task price
state integer Task status
title string Task name
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
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
hasPayout boolean Indicates whether a payout has occurred or not
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
serviceFeeCompensation integer Freelancer's commission compensation amount
compensateWorkerServiceFee boolean Indicates if the freelancer’s service fee is compensated by the client
serviceFeeCompensationPercent integer Percentage of task cost for freelancer's commission compensation

Creating a Task

Sample request

curl -X POST "https://my.mellow.io/api/customer/tasks" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -d '{
        "uuid": "9b1c5a73-2f9e-4c18-9bc6-8390a12d6fb8",
        "categoryId": 42,
        "attributes": [
          {
            "id": 42,
            "value": "5"
          }
        ],
        "acceptanceFileIds": [
          102, 105
        ],
        "copyright": true,
        "needReport": false,
        "title": "Market Analysis Report",
        "description": "Detailed report on market trends and projections for Q3 2022",
        "externalId": "MAR-20220622",
        "fileIds": [
          102, 103, 104
        ],
        "workerId": 15,
        "editGroup": [
          105, 107
        ],
        "deadline": "2022-07-15T17:00:00.000Z",
        "price": 1500,
        "validateOnly": true,
        "needInsurance": true,
        "compensateWorkerServiceFee": true,
        "advData": {
          "endContracts": [
            {
              "uuid": "ab2c9d18-f712-4f8a-91d7-5fa3a7bc7b8e",
              "sum": 300
            },
            {
              "uuid": "dfe546b8-3a9d-4e4c-b49c-7ad2c99f1b2e",
              "sum": 450
            },
            {
              "uuid": "c123f0b5-568d-4b3f-91d4-2b2e7d71f8ae",
              "sum": 500
            }
          ]
        }
      }
'

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 ID 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 (without creating a task)
advData object No Data for ensuring compliance with the ad labeling law. To learn more, see here. For breakdown (itemization), add multiple contracts per task. If task amount exceeds contracts, surplus is classified as Ad Production
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, required if task has multiple contracts. Optional if there's only one contract. See here
shareCommission boolean No Indicates whether the commission is shared with the freelancer (if 0, commission is fully paid by the client, if 1, 1% of client's commission is compensated by the freelancer). If unspecified, 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.mellow.io/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
Parameter
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.mellow.io/api/customer/tasks/c6e8e285-1e0a-4a11-a676-89211c0adccc" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."

Sample response

HTTP status code: 200 OK

{
  "state": 3
}

This method is used to change the task status based on the freelancer's actions. Before using this request, please contact Mellow 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.

Request

HTTP Request
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
Request body
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).
Response

A successful request returns an empty response.

Возможные ошибки:

Possible errors:

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

Changing Deadline

Sample request

curl -X POST "https://my.mellow.io/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.

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.
deadline date Yes Date of the new deadline in 2022-07-25T15:00:58.295Z format
Response

A successful request returns an empty response.

Checking for Issues Prior to Task Start

Sample request

curl -X GET "http://my.mellow.io/api/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

{
  "url": "http://my.mellow.io/agreement",
  "templateUuid": "1as7ac19-5y33-4a3a-94b3-b4a26374de4d"
}

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:

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

Response

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.mellow.io/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 body

No additional parameters are required.

Response

A successful request returns an empty response.

Pay for Task

Sample request

curl -X POST "https://my.mellow.io/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
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.mellow.io/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.mellow.io/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:

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.mellow.io/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 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 Mellow, which is returned when you request company details for the advertising data operator (the contract with Mellow has the value true for the 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, 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.mellow.io/api/customer/ord/organization" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "externalOrganisationId": "4fc2b18c-8e2b-41f1-a12e-d3b9e5b87fa4",
        "fullOpf": "ООО Альтаир",
        "inn": "7701234567",
        "ogrn": "1027700132195",
        "regionNumber": "78"
    }"

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:

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.mellow.io/api/customer/ord/organization" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json"

Sample response

HTTP status code: 200 OK

{
"items": [
  {
    "uuid": "b913d8fa-cf7a-4d2e-8c3a-0b23688e2a10",
    "title": "ООО Вектор",
    "type": "organisation",
    "isPrimary": true
  },
  {
    "uuid": "c821f2db-af6b-4f98-8b7a-1a32765f4cbe",
    "title": "ЗАО ПромТех",
    "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.

Response
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.mellow.io/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": "be4fd12c-abc3-47d9-bde7-5a2b3cbb4f6a",
    "inn": "7701234567",
    "isOpc": true,
    "isPp": false,
    "fio": "Иванов Иван Иванович",
    "fullOpf": "АО Сигма",
    "individualAccountDescription": " ",
    "legalType": "LEGAL_TYPE_LEGAL",
    "ogrn": "1047700060100",
    "ogrnip": "",
    "paymentNumber": "40802810700000012345",
    "phoneNumber": "+7 (495) 123-45-67",
    "regionNumber": "77",
    "platforms": [
      {
        "externalPlatformId": "f5c2b94d-dc2e-4c8e-8e3d-f7127b3448b1",
        "isPlatformOwner": true
      }
    ],
    "postAddress": "г. Москва, ул. Тверская, д. 1",
    "regionNumber": "77",
    "registrationNumber": "123456789",
    "shortOpf": "АО Сигма",
    "taxId": "1234567890",
    "trustedPerson": "Петров Петр Петрович",
    "violationDescription": " " },
  "uuid": "c6f7e1bc-3fa8-4d23-910d-8d2f1a234bcd",
  "title": "ООО Альфа",
  "type": "organisation",
  "isPrimary": true
}

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 Mellow 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 Mellow 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.mellow.io/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.mellow.io/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.

Response
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.mellow.io/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": "d482f2c7-dcb3-4c0a-bb1d-2eac70c5d3a4",
    "contractType": "CONTRACT_TYPE_SERVICE",
    "externalOrganisationCustomerId": "af1d8b34-bb4a-4d77-9ec4-3eac2f35c5a9",
    "externalOrganisationPerformerId": "bf2d3c56-ca4f-4e89-8b2d-4fb1a8c3e2d3",
    "isCreativeReporter": true,
    "actionType": "ACTION_TYPE_APPROVAL",
    "subjectType": "SUBJECT_TYPE_CONSULTING",
    "contractNumber": "2022-001",
    "contractDate": "2022-09-15",
    "additionalContractNumber": "2022-001-A",
    "additionalContractNumberDate": "2022-09-20",
    "price": "1500.00",
    "withNds": true,
    "externalParentId": "f1a8e3b6-9d7c-4b5c-a678-1a2f5c6e4d8f",
    "createdAt": "2022-09-15T08:30:00.000Z",
    "editedAt": "2022-10-01T17:45:00.000Z",
    "createdBy": {
      "id": "153",
      "email": "[email protected]",
      "name": "Иванов Максим"},
    "editedBy": {
      "id": "154",
      "email": "[email protected]",
      "name": "Петров Иван"} },
  "uuid": "b293f2a1-4b6f-44b7-bd1a-9a2c6f2b3d1f",
  "title": "Consulting Contract - Client A & Partner B",
  "type": "contract",
  "isPrimary": true
}

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 not defined
  • ACTION_TYPE_CONCLUSION: Contract signing
  • ACTION_TYPE_DISTRIBUTION: Ad distribution
  • ACTION_TYPE_COMMERCIAL: Commercial representation
  • ACTION_TYPE_OTHER: Other intermediary action
data.subjectType string Information about the contract's subject:
  • SUBJECT_TYPE_INVALID: Not defined
  • SUBJECT_TYPE_DISTRIBUTION: Ad distribution contract
  • SUBJECT_TYPE_ORGANIZATION: Ad distribution organization contract
  • 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 if VAT was applied to the price
data.externalParentId uuid Parent contract UUID
data.createdAt string Date contract was added to the advertising data operator (ADO)
data.editedAt string Date of contract data update 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 if it is a contract with the end customer

Retrieving Contract Details by Task ID

Sample request

curl -X GET "https://my.mellow.io/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": "Mellow",
    "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 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 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 if contractor must register creatives
endContract.price float Contract price (if applicable)
endContract.subjectType string Contract subject type:
  • SUBJECT_TYPE_INVALID: Undefined
  • SUBJECT_TYPE_DISTRIBUTION: Ad distribution
  • SUBJECT_TYPE_ORGANIZATION: Organization of ad distribution
  • SUBJECT_TYPE_INTERMEDIARY: Intermediary activities
  • SUBJECT_TYPE_REPRESENTATION: Representation activities
  • SUBJECT_TYPE_OTHER: Other
endContract.withNds string Indicates if VAT was applied
endContracts string Contract UUID
endContract object All contracts in the counterparty chain, structure mirrors endContract
customerContract object End contract of the first customer, structure mirrors endContract
workerAgreement.customerName string Customer's name in contractor agreement
workerAgreement.customerTaxValue string Customer's taxpayer ID in contractor agreement
workerAgreement.customerPhone string Customer's phone number in contractor agreement
workerAgreement.performerName string Contractor name
workerAgreement.performerPhone string Phone number
workerAgreement.performerCountry string Contractor's country
workerAgreement.performerTaxValue string Contractor's taxpayer ID
workerAgreement.contractNumber string Contract number
workerAgreement.contractDate string Contract date
workerAgreement.sum string Contract amount
workerAgreement.currency.currency string Contract currency
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.mellow.io/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.mellow.io/api/customer/tasks/messages" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
            "taskId":583689,
            "message":"Task is ready, let's go"
        }"

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.mellow.io/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.

Response
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.mellow.io/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
Response
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.mellow.io/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.

Request

HTTP Request
Request body
Parameter Type Required Description
title string Yes New task group name
Response
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.mellow.io/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
Response
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.mellow.io/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

This section details methods for managing freelancers, including:

Retrieving Freelancer List

Sample request

curl -X GET "https://my.mellow.io/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": 1,
      "uuid": "9b2cf17c-8f33-4e7a-89b4-c5a1d2630de4",
      "email": "[email protected]",
      "name": "Alexey Mironov",
      "taxationStatusId": 3,
      "taxationBlockedTill": "2022-12-31",
      "categoryTitle": "Consultant",
      "categoryTitleEn": "Consultant",
      "details": {
        "firstName": "Alexey",
        "lastName": "Mironov",
        "note": "Financial issues specialist",
        "specialization": "Financial consultant"
      },
      "country": "RU",
      "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 No Tax status ID. Possible values:
  • 1: Individual
  • 3: Self-employed
  • 4: Individual entrepreneur
filter[isVerified] boolean No Indicates whether the freelancer account is verified
filter[isInviteEmailSent] boolean No Indicates whether an invite has been sent to the freelancer
filter[dateInvitedFrom] string No Invite date (start of interval)
filter[dateInvitedTo] string No 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 Current page number
pagination.pages integer Total pages

Finding Freelancers by Email

Sample request

curl -X GET "https://my.mellow.io/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": 12,
  "email": "[email protected]",
  "name": "Michael Adams",
  "taxationStatusId": 0,
  "taxationBlockedTill": "",
  "categoryTitle": "Developer",
  "categoryTitleEn": "Developer",
  "details": {
    "firstName": "Michael",
    "lastName": "Adams",
    "note": "Experienced in building scalable web applications using modern technologies like React, Node.js, and PostgreSQL.",
    "specialization": "Full-Stack Developer"
  },
  "country": "US",
  "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 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 (e.g., "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
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.mellow.io/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": 45,
  "email": "[email protected]",
  "name": "Alex Smith",
  "taxationStatusId": 2,
  "taxationBlockedTill": "2023-10-01",
  "categoryTitle": "Software Engineer",
  "categoryTitleEn": "Software Engineer",
  "details": {
    "firstName": "Alex",
    "lastName": "Smith",
    "note": "Skilled in backend development with extensive experience in Python, Django, and cloud infrastructure.",
    "specialization": "Backend Developer"
  },
  "country": "CA",
  "isVerified": true,
  "isInviteSent": true,
  "inviteSentAt": "2022-01-15T12:30:00.000Z",
  "registerDate": "2022-01-16T09:00:00.000Z",
  "isRegistered": true
}

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 (e.g., "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
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.mellow.io/api/customer/freelancers/12" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json"

Sample response

HTTP status code: 200 OK

{
  "id": 78,
  "email": "[email protected]",
  "name": "Sophia Johnson",
  "taxationStatusId": 4,
  "taxationBlockedTill": "2025-01-01",
  "categoryTitle": "UI/UX Designer",
  "categoryTitleEn": "UI/UX Designer",
  "details": {
    "firstName": "Sophia",
    "lastName": "Johnson",
    "note": "Expert in creating user-centered designs with a focus on usability and aesthetics. Proficient in Figma and Adobe XD.",
    "specialization": "UI/UX Design"
  },
  "country": "DE",
  "isVerified": true,
  "isInviteSent": true,
  "inviteSentAt": "2023-05-20T14:15:00.000Z",
  "registerDate": "2023-05-21T10:00:00.000Z",
  "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.

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 (e.g., "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
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 Freelancer

Sample request

curl -X POST "https://my.mellow.io/api/customer/freelancers" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "email": "[email protected]",
        "note": "Experienced frontend developer with a focus on React and TypeScript.",
        "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 in one of two ways:

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.mellow.io/api/customer/freelancers" 
    -H  "Accept: application/json" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "freelancerId": 25,
        "firstName": "Emma",
        "lastName": "Brown",
        "note": "Skilled backend developer with expertise in Node.js and MongoDB.",
        "specialization": "Backend Developer",
        "freelancerUuid": "a7d53c21-e6f2-42f8-b78b-1f9b90b4c123",
        "companyId": 5
      }"

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.mellow.io/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 allows you to update a freelancer's contact details, specifically their phone number or email. When making the request, provide the freelancer's updated contact information and their ID. Following the request, a code will be sent to the freelancer, which must then be included in the /api/customer/freelancers/change-contacts request for further verification.

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

Upon successful execution of the request, a code is returned, which must be included in the /api/customer/freelancers/change-contacts request (see further details below).

Confirming Change of Contact Details

Sample request

curl -X POST "https://my.mellow.io/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 request below in JSON format. Ensure the request includes the unique code received after the initial request to change the contact details, along with the freelancer's ID. If the code is valid, the freelancer's contact details will be updated to those specified in the 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.

Sample request

curl -X GET "https://my.mellow.io/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 string No URL where the freelancer will be redirected after verification

Response

Property Name Type Description
terminal_url string URL of the verification page

Change Freelancer's Taxation Status

Sample request

curl -X POST "https://my.mellow.io/api/customer/freelancers/change-taxation-status" 
    -H  "Accept: application/json" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "freelancerId": 123,
        "taxationStatusId": 1
      }"


Sample request with UUID:


curl -X POST "https://my.mellow.io/api/customer/freelancers/change-taxation-status" 
    -H  "Accept: application/json" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."
    -H  "Content-Type: application/json" 
    -d "{
        "freelancerUuid": "8e947213-c114-41ec-a9ae-0242ac130002",
        "taxationStatusId": 1
      }"

Sample response

HTTP status code: 200 OK

{
  "linkToTerminal": "http://link.com"
}

This request is used to change the taxation status of a freelancer (applicable only to freelancers from Russia):

For more information about taxation statuses for Russian freelancers, see here).

Request

HTTP Request
Request body
Parameter Type Required Description
freelancerId integer One of freelancerId or freelancerUuid is required Freelancer ID
freelancerUuid uuid One of freelancerId or freelancerUuid is required Freelancer UUID, for example, 8e947213-c114-41ec-a9ae-0242ac130002
taxationStatusId integer Yes Taxation status ID. Possible values:
  • 1 - individual
  • 3 - self-employed
  • 4 - individual entrepreneur

Response

Property Name Type Description
linkToTerminal string URL of the terminal for changing the taxation status

Adding Freelancer's Taxpayer ID Number

Sample request

curl -X POST "https://my.mellow.io/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.mellow.io/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

Response

A successful request returns an empty response.

Removing Freelancers from Team

Sample request

curl -X DELETE "https://my.mellow.io/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.mellow.io/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 allows you to sign the offer agreement on behalf of the freelancer. The request that checks for new offers returns the offer ID, which needs to be provided in the Accepting Offer Agreement request. Additionally, a link for viewing the offer is provided, 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 Mellow, 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.mellow.io/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.mellow.io/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.

Response

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.mellow.io/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.mellow.io/api/customer/freelancers/payout-endpoints?freelancerId=1' \

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": []
}

his 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 Payment method type. 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
  • 3: Card blocked
  • 4: Card added and verified
  • 7: Card deleted
.
cards.cardType string Bank card type. Possible values:
  • 1: Visa
  • 2: Mastercard
  • 3: Maestro
  • 8: Mir
  • 0: Undefined
.
cards.type string Payment method type. 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: Account added but not verified
  • 1: Account verified
  • 2: Account deleted
.
iban.bankAccountType string Account type. Possible values:
  • 1: SEPA
  • 2: SWIFT
  • 6: BIC
.
iban.type string Payment method type. 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.mellow.io/api/customer/freelancers/cards' \
  --data-raw '{
        "code": 583695,
        "freelancerId": 1
    }'

Sample response

HTTP status 200 OK

{
  "redirect": "https://link-to-payment-terminal"
}

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:

  1. Request a code to be sent to the freelancer's phone.
  2. 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 string 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.mellow.io/api/customer/freelancers/bank-accounts' \
  --data-raw '{
        "code": 583695,
        "freelancerId": 1
    }'

Sample response

HTTP status 200 OK

{
  "redirect": "https://link-to-payment-terminal"
}

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:

  1. Request a code to be sent to the freelancer's phone.
  2. 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 No 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.mellow.io/api/customer/freelancers/wallets' \
  --data-raw '{
        "code": 583695,
        "freelancerId": 1
    }'

Sample response

HTTP status 200 OK

{
  "redirect": "https://link-to-payment-terminal"
}

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 e-wallet is done as follows:

  1. Request a code to be sent to the freelancer's phone.
  2. 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.mellow.io/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.mellow.io/api/customer/freelancers/wallets/123?freelancerId=123' \

Sample response

HTTP status 200 OK

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

Request

HTTP Request
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.mellow.io/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

Response

A successful request returns an empty response.

Requesting Code for Adding New Payment Method

Sample request

curl --location 
  --request POST 'https://my.mellow.io/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.mellow.io/api/customer/companies" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..."

Sample response

HTTP status code: 200 OK

{
  "items": [
    {
      "id": 2955,
      "companyName": "Skyline Ltd",
      "brandName": "Skyline",
      "safeDealEnabled": true,
      "isDefault": true,
      "currency": {
        "currency": "USD",
        "id": 2
      }
    }
  ],
  "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.mellow.io/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

Response

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

Retrieving Company Balance

Sample request

curl -X GET "https://my.mellow.io/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.

Response

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.mellow.io/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
.

Response

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.mellow.io/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.

Retrieving Personal Details

Sample request

curl --location 
    --request POST 'https://my.mellow.io/api/profile' \

Sample response

HTTP status code: 200 OK

{
  "languageStringValue": "EN",
  "name": "John Doe",
  "postCode": "90210",
  "physicalAddress": "Los Angeles, Sunset Blvd 123",
  "city": "Los Angeles",
  "inn": "456456456",
  "ip": "192.168.0.1",
  "birthDate": "1985-07-12",
  "gridsSettings": "{}",
  "loginNotification": true,
  "id": 100,
  "uuid": "2b69eb5d-e0e3-11ec-95b5-fa84c4fedfee",
  "email": "[email protected]",
  "username": "[email protected]",
  "firstName": "John",
  "middleName": "",
  "lastName": "Doe",
  "regDate": "2020-10-30",
  "twoFaMethod": "sms",
  "taxationStatus": 1,
  "phone": "+1-555-5555",
  "country": "US",
  "state": null,
  "flags": 0,
  "type": "customer",
  "defaultSmsGate": null,
  "language": "EN",
  "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)

Changing Language

Sample request

curl -X PUT "https://my.mellow.io/api/profile/language" \
    -H "accept: */*" \
    -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." \
    -H "Content-Type: application/json" \
    -d '{
          "language": "EN"
        }'

Sample response

HTTP status code: 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.mellow.io/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
<currency code> integer Currency ID

Currency Conversion Rate

Sample request

curl --location 
  --request GET 'https://my.mellow.io/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 Name of the target currency of conversion
target.id integer ID of the target currency of conversion
rate float Conversion rate

Tax Statuses

Sample request

curl --location 
  --request GET 'https://my.mellow.io/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

There are no additional 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.mellow.io/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.mellow.io/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 Required 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.mellow.io/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.

Request

HTTP Request

Path-parameters

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

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.mellow.io/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.mellow.io/api/lookups/specializations' \

Sample response

HTTP status 200 OK

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

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.mellow.io/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 Mellow. 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. Mellow 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:

Sample message that is sent to the specified URL:

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

Parameters:

Event Description Payload
bankAccountAdded Bank account added id - Bank account ID, ownerId - Freelancer ID, uuid - Freelancer UUID
bankAccountRemoved Bank account removed id - Bank account ID, ownerId - Freelancer ID, uuid - Freelancer UUID
cardAdded Payment method (bank card) added id - Card ID, ownerId - Freelancer ID, uuid - Freelancer UUID
cardRemoved Payment method (bank card) removed id - Card ID, ownerId - Freelancer ID, uuid - Freelancer UUID
walletAdded Wallet added id - Wallet ID, ownerId - Freelancer ID, uuid - Freelancer UUID
walletRemoved Wallet removed id - Wallet ID, ownerId - Freelancer ID, uuid - Freelancer UUID
freelancerRegistered Freelancer registered uuid - Freelancer UUID
freelancerVerified Freelancer successfully verified uuid - Freelancer UUID
taxationStatusChanged Freelancer taxation status changed uuid - Freelancer UUID, taxationStatusId - New taxation status ID

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

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), Mellow will keep attempting to send the notification for the next 24 hours.

Retrieve Webhook

Sample request

curl --location 
  --request GET 'https://my.mellow.io/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

There are no additional request 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.mellow.io/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.mellow.io/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

There are no additional request parameters.

Response

A successful request returns an empty response.

Release Notes

August 2024

Added:

June 2024

Added:

April 2024

Added:

November 2023

Added:

October 2023

Added:

August 2023

Added:

July 2023

Added: