Creating receivers

When making API requests to our system, it is important to include the authorization token in the Authorization header to authenticate your requests. The correct format for including the token is:

Authorization: Bearer ${ACCESS_TOKEN}

For detailed information on obtaining and using access tokens, please refer to the Authentication section of our documentation.

Create receiver

Create a new receiver

Creates a new receiver for the current authenticated user.

POST/receivers

Authorization

Access Token

Body

application/json

firstNamestring

lastNamestring

legalNamestring

address*string

type*enum

COMPANYINDIVIDUAL

countryIsoCode*string

email*string

Response

201

Request

JavaScriptCurl

const response = await fetch('/receivers', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer Bearer",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "address": "text",
      "type": "COMPANY",
      "countryIsoCode": "text",
      "email": "text"
    }),
});
const data = await response.json();

Creates a new receiver for the currently authenticated user by providing the following information:

• Receiver type - COMPANY

{
  "legalName": "ABC Inc.",
  "address": "123 Main St.",
  "type": "COMPANY",
  "countryIsoCode": "US",
  "email": "[e-mail]"
}

• Receiver type - INDIVIDUAL

{
  "firstName": "John",
  "lastName": "Mayer",
  "address": "123 Main St.",
  "type": "INDIVIDUAL",
  "countryIsoCode": "US",
  "email": "[e-mail]"
}

If the receiver was successfully created, you will receive information about the newly created receiver as shown below:

{
  "firstName": null,
  "lastName": null,
  "legalName": "ABC Inc.",
  "address": "123 Main St.",
  "type": "COMPANY",
  "email": "[e-mail]",
  "owner": "63ebc79156940ab1c9c32210",
  "country": {
    "_id": "63ebc49a227fcc69535bb949",
    "name": "United States",
    "isoCode3166": "US",
    "continent": "NA",
    "createdAt": "2023-02-14T17:27:54.382Z",
    "updatedAt": "2023-02-14T17:27:54.382Z",
    "__v": 0
  },
  "_id": "642312c96eb191e45530ea2d",
  "createdAt": "2023-03-28T16:16:09.447Z",
  "updatedAt": "2023-03-28T16:16:09.447Z"
}

Note: Country information is available through our Country endpoint

Get a receiver by ID

Get a receiver by id owned by the current authenticated user

Retrieves a receiver by id owned by the current authenticated user.

GET/receivers/{id}

Authorization

Access Token

Path parameters

id*string

Response

200

Request

JavaScriptCurl

const response = await fetch('/receivers/{id}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer Bearer"
    },
});
const data = await response.json();

Retrieves a receiver by id

If the receiver is associated with the currently authenticated user, a 200 status code will be returned, accompanied by the receiver's details. Conversely, if the receiver cannot be located or is not linked to the current user, a 404 status code will be generated, along with an error message.

Example Response (Success):

{
  "_id": "642312c96eb191e45530ea2d",
  "firstName": null,
  "lastName": null,
  "legalName": "ABC Inc.",
  "address": "123 Main St.",
  "type": "COMPANY",
  "email": "[e-mail]",
  "owner": "63ebc79156940ab1c9c32210",
  "country": {
    "_id": "63ebc49a227fcc69535bb949",
    "name": "United States",
    "isoCode3166": "US",
    "continent": "NA",
    "createdAt": "2023-02-14T17:27:54.382Z",
    "updatedAt": "2023-02-14T17:27:54.382Z",
    "__v": 0
  },
  "createdAt": "2023-03-28T16:16:09.447Z",
  "updatedAt": "2023-03-28T16:16:09.447Z"
}

Example Response (Error):

{
  "statusCode": 404,
  "message": "Receiver not found",
  "error": "Not Found"
}

Update a receiver by ID

Update a receiver owned by the current authenticated user

Updates a receiver owned by the current authenticated user.

PATCH/receivers/{id}

Authorization

Access Token

Path parameters

id*string

Body

application/json

address*string

countryIsoCode*string

email*string

Response

200

Request

JavaScriptCurl

const response = await fetch('/receivers/{id}', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer Bearer",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "address": "text",
      "countryIsoCode": "text",
      "email": "text"
    }),
});
const data = await response.json();

Modifies a receiver with a specified ID belonging to the currently authenticated user.

Below is a sample update payload:

{
  "address": "123 Main St.",
  "countryIsoCode": "PT",
  "email": "[e-mail]"
}

If the receiver was successfully updated, the API will return the updated receiver entity with the following properties:

{
  "_id": "642312c96eb191e45530ea2d",
  "firstName": null,
  "lastName": null,
  "legalName": "ABC Inc.",
  "address": "123 Main St.",
  "type": "COMPANY",
  "email": "[e-mail]",
  "owner": "63ebc79156940ab1c9c32210",
  "country": {
    "_id": "63ebc49a227fcc69535bb949",
    "name": "United States",
    "isoCode3166": "US",
    "continent": "NA",
    "createdAt": "2023-02-14T17:27:54.382Z",
    "updatedAt": "2023-02-14T17:27:54.382Z",
    "__v": 0
  },
  "createdAt": "2023-03-28T16:16:09.447Z",
  "updatedAt": "2023-03-28T16:52:52.304Z"
}

If the current user lacks permission to update the receiver, a response with a 403 Forbidden status code will be returned, accompanied by a message indicating the user's insufficient access rights to modify the receiver:

{
  "statusCode": 403,
  "message": "This user can't update this receiver",
  "error": "Forbidden"
}

If the specified receiver does not exist, you will receive a response with a 404 Not Found status code and a message indicating that the receiver could not be found:

{
  "statusCode": 404,
  "message": "This receiver doesn't exist",
  "error": "Forbidden"
}