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

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

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

{
    "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

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

{
  "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:

Invite freelancers
Create tasks
Change task statuses
Pay for tasks

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

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:

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

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

Use_case_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.
Create a new task.
The freelancer confirms and completes the task.
Accept the task.
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

Find or invite a freelancer.
Create a new task.
Change task statuses in sequence: "Accepted by freelancer", "Completed".
Accept the task.
Pay for the task.
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.
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:

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

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

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

The request's method and URI: PUT https://my.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
`Draft`	`ID=17`	Task created as draft	Customer
`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

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

{
  "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
      },
      "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
`workerCurrency`	`string`	The currency in which the freelancer will receive funds
`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
`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

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

{
  "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
  },
  "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
`workerCurrency`	`string`	The currency in which the freelancer will receive funds
`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
`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

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,
        "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
            }
          ]
        }
      }
'

The method is used to create new tasks.

The endpoint now supports the workerCurrency parameter, allowing you to specify the currency (USD, EUR, RUB) in which the freelancer will receive payment. If the selected currency differs from your account balance currency, the system automatically converts the task amount using the service rate at the moment of task creation. If there are insufficient funds, the task will be created in draft status.

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
`workerCurrency`	`string`	No	Currency in which the freelancer will receive the funds. Supported values can be retrieved using the Get Allowed Currencies for Multicurrency Tasks. If different from the customer's balance currency, the amount will be automatically converted at the current service rate. If there are insufficient funds, the task will be created in draft status. You can later publish the draft using the Publishing a Draft Task request.
`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)
`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.

Publishing a Draft Task

curl -X POST "https://my.mellow.io/api/customer/tasks/publish-draft" 
    -H  "accept: */*" 
    -H  "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." 
    -d '{
        "taskId": 12345,
        "uuid": "8e947213-c114-41ec-a9ae-0242ac130002",
        "companyId": 2
    }'

{
  "uuid": "8e947213-c114-41ec-a9ae-0242ac130002"
}

This method is used to publish a previously created draft task and move it to active status.

The task will only be published if the account has sufficient funds. If the publication is successful, the task will become available to the freelancer.

Request

HTTP Request

Request body

Parameter	Type	Required	Description
`taskId`	`integer`	No	ID of the task. If both `taskId` and `uuid` are provided, `taskId` will be used
`uuid`	`string`	No	UUID of the task. Can be used instead of `taskId`
`companyId`	`integer`	Yes	ID of the company (tenant). Required if you manage multiple companies under your account

Response

Property	Type	Description
`uuid`	`string`	UUID of the published task

If an error occurs (e.g., insufficient funds), a corresponding error message will be returned.

Get allowed currencies for multicurrency tasks

curl -X GET "https://my.mellow.io/api/customer/tasks/allowed-currencies-for-multicurrency?companyId=YOUR_COMPANY_ID" \
  -H "accept: */*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

[
  {
    "id": 1,
    "currency": "USD"
  },
  {
    "id": 2,
    "currency": "EUR"
  }
]

Retrieves the list of currencies allowed for tasks with multicurrency options, specific to a certain company.

Request

HTTP Request

Parameters

Parameter	Type	Required	Description
companyId	number	yes	Unique company identifier

Response

Property	Type	Description
id	number	Unique identifier for the currency
currency	string	Currency code (e.g., "USD", "EUR")

Calculate total cost for task

curl -X POST "https://my.mellow.io/api/customer/tasks/total-cost" \
  -H "accept: */*" \
  -H "Authorization: Bearer At__4mVoDg_6dx4TEXOKc_azImBl..." \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "cbe8003e-e9e0-46a9-b15b-7c0227273b2e",
    "price": 1,
    "workerCurrency": "USD",
    "shareCommission": false,
    "workerId": 101048,
    "categoryId": 18,
    "companyId": 2853
}'

{
  "price": 0.95,
  "commission": 0.1,
  "commissionPercent": 10,
  "shareCommission": false,
  "sharedCommission": 0,
  "salesTax": 0,
  "total": 1.05,
  "amountForWorker": 1,
  "VAT": 0.21,
  "VATPercent": 20,
  "currency": {
    "id": 3,
    "currency": "EUR"
  },
  "workerCurrency": {
    "id": 2,
    "currency": "USD"
  },
  "priceWithActualCurrencyExchangeRate": {
    "isChanged": false,
    "price": 0.95,
    "commission": 0.1,
    "commissionPercent": 10,
    "shareCommission": false,
    "sharedCommission": 0,
    "salesTax": 0,
    "total": 1.05,
    "amountForWorker": 1,
    "VAT": 0.21,
    "VATPercent": 20,
    "currency": {
      "id": 3,
      "currency": "EUR"
    },
    "workerCurrency": {
      "id": 2,
      "currency": "USD"
    }
  },
  "exchangeRate": {
    "base": {
      "id": 2,
      "currency": "USD"
    },
    "target": {
      "id": 3,
      "currency": "EUR"
    },
    "rate": 1.0576
  }
}

Calculates total cost, sales tax, and today's currency conversion for a task that involves multiple currencies. This is particularly useful for projects where the freelancer's payment currency differs from the client's balance currency.

Request

HTTP Request

Request body

Parameter	Type	Required	Description
uuid	string	yes	Task UUID
price	number	yes	Task price
workerCurrency	string	yes	Worker's currency code (e.g., "USD")
shareCommission	boolean	yes	Whether to share the commission
workerId	number	yes	Worker ID
categoryId	number	yes	Category ID
companyId	number	yes	Company ID

Response

Property	Type	Description
price	number	Base price used for calculation
commission	number	Commission amount
commissionPercent	number	Commission percent
shareCommission	boolean	Whether commission is shared
sharedCommission	number	Shared commission amount
salesTax	number	Sales tax amount (applicable only for companies in the USA)
total	number	Total amount including taxes and commissions
amountForWorker	number	Amount allocated for the worker
VAT	number	Value Added Tax (VAT) amount
VATPercent	number	VAT percent
currency	object	Target currency (`id`, `currency`)
workerCurrency	object	Worker's currency (`id`, `currency`)
priceWithActualCurrencyExchangeRate	object	Calculation with current exchange rate (full object, as root)
exchangeRate	object	Currency exchange rate (`base`, `target`, `rate`)

Changing Task Status

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

{
  "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:

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

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

Changing Deadline

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

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

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"

{
  "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:

The offer agreement needs to be re-signed. You need to have the new offer agreement shown to the freelancer, ensure they agree to it, and call the "Accept offer on behalf of freelancer" request.
Freelancer needs to get verified.
Freelancer needs to accept non-disclosure documents (NDA).

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

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

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

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

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

Request

HTTP Request

Request body

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

Response

A successful request returns an empty response.

Pay for Task upon Creation

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

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

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

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

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

Request

HTTP Request

Request body

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

Response

A successful request returns an empty response.

Resume Task

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

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.

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

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

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"
        }"

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

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

{
  "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

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"
    }"

{
  "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

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"
    }"

{
  "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

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
    }"

{
  "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

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"
    }'

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:

Invite a freelancer
Change freelancer details
Remove freelancer from the client's team

Retrieving Freelancer List

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

{
  "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

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

{
  "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

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"

{
  "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

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

{
  "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

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
      }
      "

{
  "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:

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

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

This request returns the UUID of the invited freelancer and, if the appropriate parameter is selected, sends an email to the freelancer with the registration link.

Alternatively, you can generate the registration link yourself using the returned UUID and send it directly to the freelancer.
To form the registration link, use the following format:

https://my.mellow.io/registration/invite?utm_source=company_invite&utm_medium=invite&invite_from={company_id}&hashtoken={freelancer_uuid}&type=freelancer-registration

invite_from — your company ID
hashtoken — the freelancer UUID returned by this request
type — freelancer-registration
utm_source — company_invite
utm_medium — invite

All URL parameters except invite_from and hashtoken remain constant as shown above.

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

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

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

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.

Generating Verification Link

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"

{
  "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

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
      }"

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

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

If the status change to "individual" is requested, the status is changed immediately, and the response will return an empty string.
If the status change to "self-employed" or "individual entrepreneur" is requested, the response will return a link to a page where the freelancer can enter their tax details.

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

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

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

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

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
      }"

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 to a freelancer's payment method
Adding payment method

Creating Payout for Task

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

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

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

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

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

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

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

{
  "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:

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

Request

HTTP Request

Request body

Name	Type	Required	Description
`code`	`integer`	Yes	Code sent to the freelancer's phone number
`freelancerId`	`integer`	Either `freelancerId` or `freelancerUuid` is required	Freelancer ID
`freelancerUuid`	`string`	Either `freelancerId` or `freelancerUuid` is required	Freelancer UUID (for example, `8e947213-c114-41ec-a9ae-0242ac130002`)
`redirectUrl`	`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

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

{
  "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:

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

Request

HTTP Request

Request body

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

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

{
  "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:

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

Request

HTTP Request

Request body

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

Response

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

Deleting Bank Card

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

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

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

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

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

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

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

{
  "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.

Working with Multiple Companies in API

In Mellow, a single account can include multiple companies.
You can add several companies to your account, manage their data separately, and automate workflows for each of them via API.

All API requests (tasks, currencies, assignees, etc.) are executed in the context of a specific company.
You cannot perform actions with data belonging to one company while using the context of another: for example, you cannot update or publish a task from Company A while the request context is set to Company B. Attempting to do so will result in an error. This company context is always required — either you set it as your active company, or you specify it in each request.

The Mellow API supports two ways to specify which company context is used for a request:

Setting the active company (PATCH /customer/companies)

Use the PATCH /customer/companies method to set the default active company.
All subsequent requests are made in the context of this company, unless you override it with x-company-id.
This approach is suitable for working with companies one at a time (sequentially or in isolation).

Passing x-company-id in the header

Add the x-company-id header to each request:
x-company-id: {company_id}
This allows you to work with different companies in parallel, without switching the active company or re-authenticating.

Retrieving User's Companies

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

{
  "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

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

{
  "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

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

{
  "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

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

{
  "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

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

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

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

{
  "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

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

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

curl --location 
  --request GET 'https://my.mellow.io/api/lookups/currencies' \

{
  "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

curl --location 
  --request GET 'https://my.mellow.io/api/exchanges' \

[
  {
    "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

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

{
  "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

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

{
  "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

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

{
  "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

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

{
  "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

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

{
  "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

curl --location 
  --request GET 'https://my.mellow.io/api/lookups/specializations' \

{
  "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

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

{
  "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:

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

Sample message that is sent to the specified URL:

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

Parameters:

name - Event name,
payload - Event data. Possible values include:
- Notifying about a payment method being added returns the parameters ownerId (ID of the user that added the method) and id (ID of the payment method).
- For freelancer registration, the uuid of the freelancer is returned.
- Changing the tax status of the contractor (only applicable for freelancers from the Russian Federation) returns the uuid of the freelancer and their tax status.
timestamp - Event date

Event	Description	Payload
`bankAccountAdded`	Bank account added	`id` - Bank account UUID, `ownerId` - Freelancer ID, `uuid` - Freelancer UUID
`bankAccountRemoved`	Bank account removed	`id` - Bank account UUID, `ownerId` - Freelancer ID, `uuid` - Freelancer UUID
`cardAdded`	Payment method (bank card) added	`id` - Card UUID, `ownerId` - Freelancer ID, `uuid` - Freelancer UUID
`cardRemoved`	Payment method (bank card) removed	`id` - Card UUID, `ownerId` - Freelancer ID, `uuid` - Freelancer UUID
`walletAdded`	Wallet added	`id` - Wallet UUID, `ownerId` - Freelancer ID, `uuid` - Freelancer UUID
`walletRemoved`	Wallet removed	`id` - Wallet UUID, `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:

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

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

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

Retrieve Webhook

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

{
  "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

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

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

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

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

June 2025

Added:

Enhanced multi-currency support in tasks. You can now specify a different currency for the freelancer's payment using the workerCurrency parameter in the task creation request.
- Check available currencies with Get Allowed Currencies for Multicurrency Tasks.
- The service will automatically convert your balance to the selected currency using the current exchange rate.
- If funds are insufficient, the task will be created as a draft.
- Publish drafts when ready using the Publishing a Draft Task method.

Minor cleanup

Removed insurance-related endpoints and parameters. These are no longer supported and have been removed from the API.

August 2024

Added:

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

June 2024

Added:

Request to retrieve the list of specializations for the freelancer.

April 2024

Added:

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

November 2023

Added:

A parameter fileId has been added to the response of the request to get a list of documents for accepting a task.
A parameter for compensating the freelancer's commission, compensateWorkerServiceFee, has been added to the task creation request.

October 2023

Added:

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