swagger: "2.0"
info:
version: 1.0.0
title: API Specifications
schemes:
- https
host: qa-ows-collaborator.theorchard.io
definitions:
Collaborator:
type: object
properties:
id:
type: integer
description: ID of the collaborator.
name:
type: string
description: Name of the collaborator.
participant_id:
type: string
description:
type: string
description: Description of the collaborator
internal_id:
type: string
description: User's internal unique identifier for the collaborator
Split:
type: object
properties:
id:
type: integer
description: ID of the collaborator.
collaborator_id:
type: integer
description: ID of the collaborator who the split is for.
split_type_id:
type: integer
description: ID of the split type.
identifier:
type: string
description: Identifier for the entity this is a split of.
split_rate:
type: number
description: Split amount (0 to 1).
rate_type:
type: string
enum: ["NET", "GROSS"]
description: Split rate type (NET or GROSS).
created_date:
type: string
description: Date the split was created.
updated_date:
type: string
description: Date the split was updated.
source:
type: string
description: Source of the split (if imported).
TransferwiseProfile:
type: object
properties:
id:
type: integer
description: ID of the transferwise profile.
vendor_id:
type: integer
description: ID of the vendor.
subaccount_id:
type: integer
description: Optional ID of the subaccount.
profile_id:
type: integer
description: The profile_id from Transferwise.
TransferwiseRecipient:
type: array
items:
type: object
properties:
currency:
type: string
description: Currency abbreviation.
type:
type: string
description: Transferwise type for given currency.
profile:
type: integer
description: The profile_id from Transferwise.
accountHolderName:
type: string
description: The name of recipient.
"details":
type: array
description: Required details for given currency
items:
type: object
TransferwiseWebhook:
type: object
properties:
name:
type: string
description: the name of the webhook
trigger_on:
type: string
description: the webhook topic trigger
TransferwiseQuote:
type: object
properties:
quotes:
type: array
description: The quotes array of objects
items:
type: object
properties:
profile:
type: integer
description: the profile id
recipient_id:
type: integer
description: the recipient's unique identifier
sourceCurrency:
type: string
description: the source currency
targetCurrency:
type: string
description: the target currency
targetAmount:
type: number
description: Amount in target currency
sourceAmount:
type: number
description: Amount in source currency
TransferwisePayment:
type: object
properties:
profile_id:
type: integer
description: the TransferWise profile id
name:
type: string
description: the batch name
transfers:
type: array
description: The transfers array of objects
items:
type: object
properties:
targetAccount:
type: integer
description: the TransferWise recipient identifier
quoteUuid:
type: string
description: The quote UUID
details:
type: object
description: payment details
properties:
reference:
type: string
description: the payment reference.
transferPurpose:
type: string
description: The transfer purpose
sourceOfFunds:
type: string
description: The source of funds e.g. salary
DpPayment:
type: object
properties:
id:
type: integer
description: ID of the DP payment.
abacus_statement_period_id:
type: integer
description: ID of the associated Abacus statement period.
abacus_statement_period_name:
type: string
description: Name of the associated Abacus statement period.
collaborator_id:
type: integer
description: ID of the collaborator.
collaborator_name:
type: string
description: Name of the collaborator.
amount:
type: number
description: Payment amount.
currency:
type: string
description: Currency code (e.g. USD).
payee_id:
type: integer
description: ID of the payee.
payoneer_program_id:
type: integer
description: ID of the Payoneer program.
payoneer_program_name:
type: string
description: Name of the Payoneer program.
payoneer_client_reference_id:
type: string
description: Payoneer client reference ID used to identify the payment.
created_date:
type: string
format: date-time
description: Date the DP payment was created.
created_by:
type: string
description: Identifier of the user who created the DP payment, or null if not tracked.
approved_date:
type: string
format: date-time
description: Date the DP payment was approved, or null if not yet approved.
approved_by:
type: string
description: Identifier of the user who approved the DP payment, or null if not yet approved.
updated_date:
type: string
format: date-time
description: Date the DP payment was last updated, or null if it has not been updated.
updated_by:
type: string
description: Identifier of the user who last updated the DP payment, or null if not tracked.
account_id:
type: integer
description: ID of the account.
account_name:
type: string
description: Name of the account.
collaborator_transaction_id:
type: integer
description: ID of the associated collaborator transaction, or null.
agreement_type:
type: string
description: Type of agreement.
payoneer_payment_id:
type: string
description: Payoneer payment ID assigned after approval file generation, or null.
payoneer_payment_status:
type: string
enum: ["init", "payment_accepted", "payment_completed", "payment_cancelled", "iach_failed"]
description: Current Payoneer payment status, or null if not yet set.
paths:
/abacus-statement-period/dataloader:
post:
summary: Dataloader endpoint for fetching Abacus statement periods by IDs.
parameters:
- in: body
name: data
description: Request body containing list of Abacus statement period IDs.
required: true
schema:
type: object
required:
- abacus_statement_period_ids
properties:
abacus_statement_period_ids:
type: array
items:
type: integer
description: List of Abacus statement period IDs to fetch.
responses:
200:
description: 200 OK
schema:
type: array
items:
type: object
properties:
data:
type: object
description: Abacus statement period data, or null if not found.
/abacus-statement-period/{abacus_statement_period_id}/dp-payments:
get:
summary: Get DP payments for an Abacus statement period.
parameters:
- in: path
name: abacus_statement_period_id
description: ID of the Abacus statement period.
type: integer
required: true
responses:
200:
description: 200 OK
schema:
type: object
properties:
currency_agnostic_total_amount:
type: number
description: Total amount across all payments, currency-agnostic.
total_count:
type: integer
description: Total number of DP payments.
payments:
type: array
items:
$ref: "#/definitions/DpPayment"
403:
description: 403 Forbidden
put:
summary: Replace DP payments for an Abacus statement period.
parameters:
- in: path
name: abacus_statement_period_id
description: ID of the Abacus statement period.
type: integer
required: true
responses:
200:
description: 200 OK
schema:
type: object
properties:
currency_agnostic_total_amount:
type: number
description: Total amount across all payments, currency-agnostic.
total_count:
type: integer
description: Total number of DP payments.
payments:
type: array
items:
$ref: "#/definitions/DpPayment"
403:
description: 403 Forbidden
patch:
summary: Perform an action on DP payments for an Abacus statement period.
parameters:
- in: path
name: abacus_statement_period_id
description: ID of the Abacus statement period.
type: integer
required: true
- in: body
name: data
required: true
schema:
type: object
required:
- action_name
properties:
action_name:
type: string
enum: ["approve"]
description: Action to perform on the DP payments.
responses:
200:
description: 200 OK
schema:
type: object
properties:
total_count:
type: integer
description: Total number of DP payments affected.
payments:
type: array
items:
$ref: "#/definitions/DpPayment"
403:
description: 403 Forbidden
/collaborators:
get:
summary: Get all collaborators for the current account.
parameters:
- in: query
name: vendor_id
description: the account unique identifier
type: string
required: false
- in: query
name: limit
description: Amount of reports to retrieve.
type: integer
default: 0
required: false
- in: query
name: offset
description: Offset for pagination.
type: integer
default: 0
required: false
- in: query
name: has_recipient
description: Flag used to fetch rows with recipient_id
type: boolean
required: false
- in: query
name: term
description: Value to search for based on the provided search dimensions
type: string
required: false
- in: dimensions
name: term
description: Dimensions to search on (e.g. id, name etc.)
type: comma-delimited value string
required: false
responses:
200:
description: 200 OK
examples:
application/json:
{
"items":
[
{
"id": 1,
"name": "Some Person",
"vendor_id": 1,
"description": "This is a Mixing Engineer",
"internal_id": "ABC-123",
},
{
"id": 2,
"name": "Another Person",
"vendor_id": 1,
"description": "This is a Mixing Engineer",
"internal_id": "ABC-123",
},
],
"pagination": { "total_records": 2, "type": "none" },
}
post:
summary: Create a collaborator.
parameters:
- in: body
name: data
description: Collaborator data.
schema:
$ref: "#/definitions/Collaborator"
required: true
responses:
201:
description: 201 Created
examples:
application/json:
{
"id": 1,
"email": "person@example.org",
"name": "Some Person",
"vendor_id": 1,
}
400:
description: 400 Missing or empty body parameters
examples:
application/json:
{
"code": "missing_body_variable",
"message": "Missing Collaborator Data",
}
/collaborators/{id}:
get:
summary: Get a single collaborator.
parameters:
- in: path
name: id
description: ID of the collaborator to get.
type: integer
required: true
responses:
200:
description: 200 OK
examples:
application/json: { "id": 1, "name": "Some Person", "vendor_id": 1 }
put:
summary: Update a collaborator.
parameters:
- in: path
name: id
description: ID of the collaborator to update.
type: integer
required: true
- in: body
name: data
description: Data to update the collaborator with.
schema:
$ref: "#/definitions/Collaborator"
required: true
responses:
200:
description: 200 OK
examples:
application/json:
{
"id": 1,
"name": "Some Person",
"vendor_id": 1,
"description": "This is a Mixing Engineer",
"internal_id": "ABC-123",
}
/collaborators/{id}/reports:
get:
summary: Get all the reports associated with a collaborator.
parameters:
- in: path
name: id
description: ID of the collaborator to get sound recordings for.
type: integer
required: true
- in: query
name: has_transaction
description: Limit the reports to only ones who have (or don't have) transactions.
type: boolean
required: false
- in: query
name: status
description: Status of the reports to get.
type: string
required: false
responses:
200:
description: 200 OK
examples:
application/json:
[
{
"user_id_type": "24601L",
"period_ids": "240",
"amount": 12.34,
"generated_date": "2020-04-01T12:34:56Z",
},
{
"user_id_type": "24601L",
"period_ids": "238,239",
"amount": 42.9001,
"generated_date": "2020-04-01T12:34:56Z",
},
]
/collaborators/{id}/balance:
get:
summary: GET the current collaborator balance.
parameters:
- in: path
name: id
description: ID of the collaborator to get sound recordings for.
type: integer
required: true
responses:
200:
description: 200 OK
examples:
application/json:
{ "collaborator_id": 1, "amount": 112.5, "currency": "USD" }
/collaborators/balances-dataloader:
post:
summary: Get balances for collaborators by ID.
parameters:
- in: body
name: collaborator_ids
description: List of collaborator IDs
schema:
type: array
items:
type: int
required: true
responses:
200:
description: 200 OK
examples:
application/json:
[
{ "data": { "amount": 2.61, "currency": "EUR" } },
{ "data": null },
]
/collaborators/{id}/transactions:
get:
summary: Get transactions by collaborator_id.
parameters:
- in: path
name: id
description: Collaborator's' unique identifier
type: integer
required: true
- in: query
name: statement_period_id
description: ID of statement period to filter transactions by.
type: integer
required: false
- in: query
name: limit
description: Amount of reports to retrieve.
type: integer
default: 0
required: false
- in: query
name: offset
description: Offset for pagination.
type: integer
default: 0
required: false
responses:
200:
description: 200 OK
examples:
application/json:
[
{
"id": 2,
"collaborator_id": 1,
"date": "2020-07-15 16:14:02",
"type": "PAYMENT",
"description": "Payment",
"original_amount": 50.0,
"collaborator_share": 1.0,
"chargeable_amount": 50.0,
"transferwise_transaction_id": 1,
"report_id": None,
"current_balance": 50.0,
"created_date": "2020-07-15 16:14:02",
"voided_transaction_id": None,
},
]
post:
summary: Create new transactions for the collaborator.
parameters:
- in: path
name: id
description: ID of the collaborator to create a transaction for.
type: integer
required: true
- in: body
name: data
description: List of transactions to create.
schema:
type: array
items:
type: object
properties:
date:
type: string
description: Date for the transaction in ISO 8601 format.
type:
type: string
enum: ["REVENUE", "PAYMENT", "EXPENSE"]
description: Type of transaction to create.
original_amount:
type: number
description: Original amount of the transaction.
collaborator_share:
type: number
description: Collaborator's share.
description:
type: string
description: Description of the transaction.
report_id:
type: integer
description: ID of the report the transaction is for.
currency:
type: string
description: The currency in the form of ISO 4217
required:
- date
- type
- original_amount
required: true
responses:
201:
description: 201 Created
examples:
application/json:
{
"id": 1,
"email": "person@example.org",
"name": "Some Person",
"vendor_id": 1,
}
400:
description: 400 Missing or empty body parameters
examples:
application/json:
{ "code": "missing_params", "message": "Missing param(s)" }
/collaborators/{id}/payments:
get:
summary: Get transferwise transactions for a collaborator with paginated response and filters based on status.
parameters:
- in: path
name: id
description: ID of the collaborator to get sound recordings for.
type: integer
required: true
- in: query
name: payment_statuses
description: array with the payment statuses as filter for the collaborator payments
type: array
required: false
- in: query
name: sort_key
description: the key to sort the results with
type: array
required: false
- in: query
name: sort_direction
description: the direction of the sort filter (ASC or DESC)
type: array
required: false
responses:
200:
description: 200 OK
examples:
application/json:
{
"items":
[
{
"collaborator_id": 4,
"conversion_rate": None,
"created_date": "2020-05-04T03:02:01",
"id": 15,
"profile_id": 12341235,
"quote_id": "81b5e5b0-e7d8-4112-aad9-b9189d53dcb2",
"recipient_id": 22223333,
"source_amount": 40.0,
"source_currency": "USD",
"status": "incoming_payment_waiting",
"status_updated_date": "2020-05-04T03:04:01",
"target_amount": 40.0,
"target_currency": "USD",
"transfer_id": 15,
"transferwise_batch_id": 3,
"transferwise_fee": 0.25,
"wire_fee": 0.25,
},
{
"collaborator_id": 4,
"conversion_rate": None,
"created_date": "2020-05-04T03:02:01",
"id": 16,
"profile_id": 12341235,
"quote_id": "81b5e5b0-e7d8-4112-aad9-b9189d53dcb2",
"recipient_id": 22223333,
"source_amount": 40.0,
"source_currency": "USD",
"status": "cancelled",
"status_updated_date": "2020-05-04T03:04:01",
"target_amount": 40.0,
"target_currency": "USD",
"transfer_id": 16,
"transferwise_batch_id": 4,
"transferwise_fee": 0.25,
"wire_fee": 0.25,
},
],
"pagination": { "total_records": 2, "type": "standard" },
}
/collaborators/{id}/statement-periods:
get:
summary: Gets statement periods for this collaborator.
parameters:
- in: query
name: statement_period_id
description: Statement Period ID to include in the total calc.
type: integer
default: null
required: false
- in: query
name: status
description: a list of comma separated statuses to filter by.
type: string
required: false
- in: query
name: limit
description: Limit for pagination.
type: integer
default: 0
required: false
- in: query
name: offset
description: Offset for pagination.
type: integer
default: 0
required: false
responses:
200:
description: 200 OK
examples:
application/json:
{
"items":
[
{
"id": 1,
"name": "SP 1",
"vendor_id": 24601,
"created_date": "2022-04-05T06:07:08",
"updated_date": "2022-04-05T06:07:08",
"status": "OPEN",
"opening_balance": { "currency": "USD", "amount": 0 },
"closing_balance": { "currency": "USD", "amount": -50.0 },
"revenues_total": { "currency": "USD", "amount": 100.0 },
"expenses_total": { "currency": "USD", "amount": -100.0 },
"payments_total": { "currency": "USD", "amount": -50.0 },
},
],
"pagination": { "total_records": 2, "type": "standard" },
}
/hello/:
get:
summary: Endpoint used for a service health check.
responses:
200:
description: 200 OK
examples:
application/json: { "status": "ok" }
/reports:
get:
summary: Get reports.
parameters:
- in: query
name: sort_key
description: Field to sort the reports by.
type: string
required: false
- in: query
name: sort_direction
description: Direction to sort the reports by.
type: string
enum: ["ASC", "DESC"]
default: "DESC"
required: false
- in: query
name: has_transaction
description: Limit the reports to only ones who have (or don't have) transactions.
type: boolean
required: false
- in: query
name: status
description: Status of the reports to get.
type: string
required: false
- in: query
name: limit
description: Amount of reports to retrieve.
type: integer
default: 10
required: false
- in: query
name: offset
description: Offset for pagination.
type: integer
default: 0
required: false
- in: query
name: report_run_uuid
description: UUID of a report run to limit reports to.
type: string
required: false
responses:
200:
description: 200 OK
examples:
application/json:
[
{
"user_id_type": "24601L",
"period_ids": "240",
"amount": 12.34,
"generated_date": "2020-04-01T12:34:56Z",
},
{
"user_id_type": "24601L",
"period_ids": "238,239",
"amount": 42.9001,
"generated_date": "2020-04-01T12:34:56Z",
},
]
post:
summary: Trigger report generation.
parameters:
- in: body
name: data
description: Data to use when triggering the report.
schema:
type: object
properties:
first_period_id:
type: integer
description: Start period ID for the periods the report is for.
last_period_id:
type: integer
description: End period ID for the periods the report is for.
period_name:
type: string
description: Name of the period the report is for.
client_email:
type: string
description: Email to send a completion mail to.
report_run_name:
type: string
description: Name of this report run.
collaborator_ids:
type: string
description: Comma-separated list of collaborators to create reports for.
required:
- first_period_id
- last_period_id
- period_name
- client_email
- report_run_name
required: true
responses:
201:
description: 201 Created
examples:
application/json:
[
{
"user_id_type": "24601L",
"period_ids": "240",
"amount": 12.34,
"generated_date": "2020-04-01T12:34:56Z",
},
{
"user_id_type": "24601L",
"period_ids": "238,239",
"amount": 42.9001,
"generated_date": "2020-04-01T12:34:56Z",
},
]
/reports/{report_id}/download:
get:
summary: Get a download link for a specific report.
parameters:
- in: path
name: report_id
description: RDS report id.
type: integer
required: true
responses:
200:
description: 200 OK
examples:
application/json: { "url": "https://s3.aws.example.org/file.rar" }
400:
description: 400 Bad Request
examples:
application/json:
{ "code": "missing_params", "message": "Missing param(s)" }
/reports/bulk-delete:
post:
summary: Bulk delete reports for a given vendor
parameters:
- in: body
name: data
description: An array of dictionaries with report ids.
schema:
type: array
description: The quotes array of objects
items:
type: object
properties:
report_ids:
type: array
description: Array of report ids
responses:
204:
description: 204 No Content
/reports/contract-subtotal-aggregations:
get:
summary: Get aggregated contract subtotals for a report run
parameters:
- in: query
name: report_run_id
type: integer
required: true
- in: query
name: collaborator_dp_enabled
type: boolean
required: false
responses:
200:
description: 200 OK - Successfully retrieved contract subtotal aggregations
400:
description: 400 Bad Request
/splits:
post:
summary: Create splits.
parameters:
- in: body
name: data
description: Split data.
schema:
type: array
items:
$ref: "#/definitions/Split"
required: true
responses:
201:
description: 201 Created
examples:
application/json:
[
{
"id": 1,
"split_type_id": "sound_recording",
"identifier": "1234ABCD",
"split_rate": 0.1,
"collaborator_id": 12,
"rate_type": "NET",
},
{
"id": 1,
"split_type_id": "sound_recording",
"identifier": "1234ABCD",
"split_rate": 0.1,
"collaborator_id": 10,
"rate_type": "GROSS",
},
]
put:
summary: Update splits.
parameters:
- in: body
name: data
description: Split data.
schema:
type: array
items:
$ref: "#/definitions/Split"
required: true
responses:
200:
description: 200 OK
examples:
application/json:
[
{
"id": 1,
"split_type_id": "sound_recording",
"identifier": "1234ABCD",
"split_rate": 0.1,
"collaborator_id": 12,
"rate_type": "NET",
},
{
"id": 1,
"split_type_id": "sound_recording",
"identifier": "1234ABCD",
"split_rate": 0.1,
"collaborator_id": 10,
"rate_type": "NET",
},
]
delete:
summary: Delete splits.
parameters:
- in: query
name: ids
description: Comma-separated IDs of splits to delete.
type: string
required: true
responses:
204:
description: 204 No Content
/splits/replace:
put:
summary: Replace splits for a product.
parameters:
- in: body
name: data
description: Split replacement data.
schema:
type: object
properties:
dp_splits_agreed:
type: boolean
description: Indicates if the T&C's are agreed.
vendor_id:
type: integer
description: ID of the vendor.
tracks:
type: array
items:
type: object
properties:
tuid:
type: string
description: Track unique identifier.
splits:
type: array
items:
type: object
properties:
id:
type: integer
description: ID of the split.
collaborator_id:
type: string
description: ID of the collaborator.
split_rate:
type: number
description: Rate of the split.
split_type_id:
type: integer
description: ID of the split type.
rate_type:
type: string
enum: ["NET", "GROSS"]
description: Type of the rate (NET or GROSS).
required: true
responses:
200:
description: 200 OK
examples:
application/json:
[
{
"id": 1,
"identifier": "123",
"split_rate": 0.1,
"split_type_id": 2,
"collaborator_id": 12345,
"rate_type": "NET",
"created_date": "2024-12-31T23:00:00",
"updated_date": "2024-12-31T23:59:59",
"source": null,
},
]
/transferwise/field-validation/{validator}:
get:
summary: Get validation for a given transferwise form field.
parameters:
- in: path
name: validator
description: The validator path e.g. sort-code
type: string
required: true
- in: query
name: field_name
description: The field name that will be used as query param key.
type: string
required: true
- in: query
name: field_value
description: The field value that will be used as query param value.
type: string
required: true
responses:
200:
description: 200 OK
examples:
application/json: { "validation": "success" }
/transferwise/profile:
post:
summary: Create a transferwise profile.
parameters:
- in: body
name: data
description: Profile data and temp code.
schema:
type: array
items:
$ref: "#/definitions/TransferwiseProfile"
required: true
responses:
201:
description: 201 Created
examples:
application/json:
{
"id": 1,
"vendor_id": 12345,
"subaccount_id": 6789,
"profile_id": 2938,
"status": "UNVERIFIED",
}
/transferwise/collaborator/{collaborator_id}/recipient:
post:
summary: Create a transferwise recipient.
parameters:
- in: path
name: collaborator_id
description: Collaborator unique identifier
type: integer
required: true
- in: body
name: data
description: Recipient data.
schema:
type: array
items:
$ref: "#/definitions/TransferwiseRecipient"
required: true
responses:
201:
description: 201 Created
examples:
application/json:
{
"id": 1,
"profile": 12345,
"currency": "GBP",
"country": "GB",
"type": "sort_code",
}
/transferwise/collaborator/{collaborator_id}/recipient/{recipient_id}:
delete:
summary: Delete a transferwise recipient.
parameters:
- in: path
name: collaborator_id
description: Collaborator unique identifier
type: integer
required: true
- in: path
name: recipient_id
description: Recipient unique identifier
type: integer
required: true
responses:
200:
description: 200 OK
/transferwise/webhook:
post:
summary: Receive a webhook event from TransferWise.
parameters:
- in: body
name: data
description: Event data.
schema:
type: object
properties:
data:
type: object
description: Data for the event (changes based on type).
event_type:
type: string
description: Type of the event.
required:
- data
- event_type
required: true
responses:
204:
description: 204 No Content
/transferwise/application-webhooks-subscription:
post:
summary: Subscribe application to webhook event.
parameters:
- in: body
name: data
description: TransferwiseWebhook data
schema:
$ref: "#/definitions/TransferwiseWebhook"
required: true
responses:
200:
description: 200 OK
/transferwise/quote:
post:
summary: create a quote for a payout.
parameters:
- in: body
name: data
description: Transferwise quote data
schema:
$ref: "#/definitions/TransferwiseQuote"
required: true
responses:
200:
description: 200 OK
/transferwise/batch-payment:
post:
summary: create a batch payment.
parameters:
- in: body
name: data
description: Transferwise quote data
schema:
$ref: "#/definitions/TransferwisePayment"
required: true
responses:
200:
description: 200 OK
examples:
application/json:
{
"id": 2,
"vendor_id": 24601,
"profile_id": 4497,
"batch_id": "54a6bc09-cef9-49a8-9041-f1f0c654cd88",
"version": 1,
"batch_name": "my-batch-group",
"amount": 123.45,
"currency": "GBP",
"wire_fee": 0.1,
"transferwise_fee": 0.92,
"status": "COMPLETED",
"type": "bank_transfer",
"reference": "XYZ123",
"payin_name": "TransferWise",
"bank_code": "231470",
"account_number": "77643994",
"iban": None,
"account_type": None,
"bban": None,
"bank_address_name": None,
"bank_address_branch_name": None,
"bank_address_first_line": None,
"bank_address_post_code": None,
"bank_address_city": None,
"bank_address_state_code": None,
"bank_address_country": None,
"tw_address_name": None,
"tw_address_first_line": None,
"tw_address_post_code": None,
"tw_address_city": None,
"tw_address_state_code": None,
"tw_address_country": None,
"created_date": "2020-11-19T16:39:10.769971",
}
/transferwise/profile/{profile_id}/batch-group/{batch_group_id}:
get:
summary: Get batch transfer group details by id.
parameters:
- in: path
name: profile_id
description: The TW profile id
type: integer
required: true
- in: path
name: batch_group_id
description: The UUID of the batch transfer group
type: string
required: true
responses:
200:
description: 200 OK
examples:
application/json:
{
"id": "8faefe82-a325-4906-a599-2f963e1fae1f",
"version": 48459408,
"name": "Test",
"sourceCurrency": "USD",
"status": "COMPLETED",
"transferIds": [48459406],
"payInDetails":
[
{
"type": "bank_transfer",
"reference": "B6072",
"amount": 21.13,
"currency": "USD",
"name": "TransferWise",
"bankCode": "091000019",
"bankAddress":
{
"name": "CFSB",
"firstLine": "8907 Jamaica Ave",
"postCode": "11421",
"city": "Jamaica",
"country": "US",
"stateCode": "NY",
},
"accountNumber": "123456789012",
"iban": null,
},
],
}
/transferwise/batch/{batch_id}/cancel:
put:
summary: Cancel a batch payment.
parameters:
- in: path
name: batch_id
description: ID of the batch to get
type: integer
required: true
- in: body
name: data
description: Batch Payment Cancellation payload.
schema:
type: object
properties:
subaccount_id:
type: integer
description: The subaccount unique identifier
required: false
responses:
200:
description: 200 OK
examples:
application/json:
{
"id": "8faefe82-a325-4906-a599-2f963e1fae1f",
"version": 48459408,
"name": "Test",
"sourceCurrency": "USD",
"status": "COMPLETED",
"transferIds": [48459406],
"payInDetails":
[
{
"type": "bank_transfer",
"reference": "B6072",
"amount": 21.13,
"currency": "USD",
"name": "TransferWise",
"bankCode": "091000019",
"bankAddress":
{
"name": "CFSB",
"firstLine": "8907 Jamaica Ave",
"postCode": "11421",
"city": "Jamaica",
"country": "US",
"stateCode": "NY",
},
"accountNumber": "123456789012",
"iban": null,
},
],
}
/transferwise/simulate/transfers/{transfer_id}/{transfer_status}:
post:
summary: Simulate transfer statuses.
parameters:
- in: path
name: transfer_id
description: The TW transfer_id
type: integer
required: true
- in: path
name: transfer_status
description: The transfer status that we want to change our transfer to.
type: string
required: true
responses:
200:
description: 200 OK
examples:
application/json:
{
"id": 48462543,
"user": 5465101,
"targetAccount": 13930523,
"sourceAccount": null,
"quote": null,
"quoteUuid": "955a6507-1ac7-4945-ac2e-37842c4ff26c",
"status": "funds_refunded",
"reference": "orch",
"rate": 1,
"created": "2020-07-08 17:20:58",
"business": 4497,
"transferRequest": null,
"details": { "reference": "orch" },
"hasActiveIssues": false,
"sourceCurrency": "USD",
"sourceValue": 0.0,
"targetCurrency": "USD",
"targetValue": 20.0,
"customerTransactionId": "71242ecd-741c-4667-9956-4816544f6414",
}
/recipient/{recipient_id}:
get:
summary: Get a recipient by id.
parameters:
- in: path
name: recipient_id
description: Recipient unique identifier
type: integer
required: true
responses:
200:
description: 200 OK
examples:
application/json:
{
"id": 1,
"name": "Joe",
"currency": "GBP",
"transferwise_id": 1,
"created_by": "alw:123",
"created_date": "2020-07-15 16:14:02",
"deleted_by": null,
"deleted_date": null,
}
/transactions/{transaction_id}/soft-delete:
delete:
summary: Soft-delete a transaction.
parameters:
- in: path
name: transaction_id
description: Transaction unique identifier
type: integer
required: true
responses:
200:
description: 200 OK
/transactions/bulk-delete:
post:
summary: Bulk delete transactions.
parameters:
- in: body
name: transaction_ids
description: List of transaction IDs to delete
schema:
type: array
items:
type: integer
responses:
204:
description: 204 No Content
/transferwise/batch/{batch_id}:
get:
summary: Get a batch by id.
parameters:
- in: path
name: batch_id
description: ID of the batch to get
type: integer
required: true
responses:
200:
description: 200 OK
examples:
application/json:
{
"id": 1,
"vendor_id": 24601,
"profile_id": 12341235,
"batch_id": "784d48fd-0f1a-49c8-bf11-fb0998714352",
"version": 1,
"batch_name": "Test Batch",
"amount": 90.0,
"currency": "USD",
"wire_fee": 0.25,
"transferwise_fee": 0.75,
"status": "test",
"batch_type": "type",
"reference": "reference",
"payin_name": "payin_name",
"bank_code": "bank_code",
"account_number": "account_number",
"iban": "iban",
"account_type": "account_type",
"bban": "bban",
"bank_address_name": "bank_address_name",
"bank_address_branch_name": "bank_address_branch_name",
"bank_address_first_line": "bank_address_first_line",
"bank_address_post_code": "bank_address_post_code",
"bank_address_city": "bank_address_city",
"bank_address_state_code": "bank_address_state_code",
"bank_address_country": "bank_address_country",
"tw_address_name": "tw_address_name",
"tw_address_first_line": "tw_address_first_line",
"tw_address_post_code": "tw_address_post_code",
"tw_address_city": "tw_address_city",
"tw_address_state_code": "tw_address_state_code",
"tw_address_country": "tw_address_country",
"created_date": "2020-05-04T03:02:01",
}
/transferwise/batches:
get:
summary: Get all batches for the account making the request.
responses:
200:
description: 200 OK
examples:
application/json:
[
{
"id": 1,
"vendor_id": 24601,
"profile_id": 12341235,
"batch_id": "784d48fd-0f1a-49c8-bf11-fb0998714352",
"version": 1,
"batch_name": "Test Batch",
"amount": 90.0,
"currency": "USD",
"wire_fee": 0.25,
"transferwise_fee": 0.75,
"status": "test",
"batch_type": "type",
"reference": "reference",
"payin_name": "payin_name",
"bank_code": "bank_code",
"account_number": "account_number",
"iban": "iban",
"account_type": "account_type",
"bban": "bban",
"bank_address_name": "bank_address_name",
"bank_address_branch_name": "bank_address_branch_name",
"bank_address_first_line": "bank_address_first_line",
"bank_address_post_code": "bank_address_post_code",
"bank_address_city": "bank_address_city",
"bank_address_state_code": "bank_address_state_code",
"bank_address_country": "bank_address_country",
"tw_address_name": "tw_address_name",
"tw_address_first_line": "tw_address_first_line",
"tw_address_post_code": "tw_address_post_code",
"tw_address_city": "tw_address_city",
"tw_address_state_code": "tw_address_state_code",
"tw_address_country": "tw_address_country",
"created_date": "2020-05-04T03:02:01",
"imputed_status": "inProgress",
},
]
/transferwise/batch/{batch_id}/transactions:
get:
summary: Get all transactions for a batch.
parameters:
- in: path
name: batch_id
description: ID of the batch to get transactions for
type: integer
required: true
responses:
200:
description: 200 OK
examples:
application/json:
[
{
"source_amount": 50.00,
"target_amount": 50.00,
"transferwise_batch_id": 1,
"source_currency": "USD",
"target_currency": "USD",
"profile_id": 12341235,
"quote_id": "81b5e5b0-e7d8-4112-aad9-b9189d53dcb2",
"recipient_id": 22223333,
"status": "OUTGOING_PAYMENT_SENT",
"id": 1,
"transfer_id": 1,
"wire_fee": 0.00,
"transferwise_fee": 0.50,
"created_date": "2020-05-04T03:02:01",
},
{
"source_amount": 40.00,
"target_amount": 40.00,
"transferwise_batch_id": 2,
"source_currency": "USD",
"target_currency": "USD",
"profile_id": 12341235,
"quote_id": "81b5e5b0-e7d8-4112-aad9-b9189d53dcb2",
"recipient_id": 22223333,
"status": "INCOMING_PAYMENT_WAITING",
"id": 2,
"transfer_id": 2,
"wire_fee": 0.25,
"transferwise_fee": 0.25,
"created_date": "2020-05-04T03:02:01",
},
]
/transferwise/transfer-requirements:
post:
summary: fetch the transfer requirements for a list of currencies.
parameters:
- in: body
name: transfers
description: List of currency code / "dummy" transfer pairs
required: true
responses:
200:
description: 200 OK
/vendor-agreement:
post:
summary: Creates a vendor agreement record.
parameters:
- in: body
name: data
description: Data to use when triggering the report.
schema:
type: object
properties:
vendor_id:
type: integer
description: The vendor's unique identifier
required:
- vendor_id
required: true
responses:
200:
description: 200 OK
examples:
application/json:
{
"id": 1,
"user_id": "7ec441df-7b21-4a71-a9da",
"vendor_id": 24601,
"date_accepted": "2006-05-04T03:02:01",
}
get:
summary: Gets a vendor agreement record.
parameters:
- in: query
name: vendor_id
description: the account unique identifier
type: string
required: true
responses:
200:
description: 200 OK
examples:
application/json:
{
"id": 1,
"user_id": "7ec441df-7b21-4a71-a9da",
"vendor_id": 24601,
"date_accepted": "2006-05-04T03:02:01",
}
/statement-periods:
get:
summary: Gets statement periods.
parameters:
- in: query
name: vendor_id
description: ID of the vendor.
type: integer
required: true
- in: query
name: statement_period_id
description: Statement Period ID to include in the total calc.
type: integer
default: null
required: false
- in: query
name: status
description: a list of comma separated statuses to filter by.
type: string
required: false
- in: query
name: limit
description: Limit for pagination.
type: integer
default: 0
required: false
- in: query
name: offset
description: Offset for pagination.
type: integer
default: 0
required: false
- in: query
name: sort_key
description: the key to sort the results with
type: string
required: false
- in: query
name: sort_direction
description: the direction of the sort filter (ASC or DESC)
type: string
required: false
responses:
200:
description: 200 OK
examples:
application/json:
{
"items":
[
{
"id": 1,
"name": "SP 1",
"vendor_id": 24601,
"created_date": "2022-04-05T06:07:08",
"updated_date": "2022-04-05T06:07:08",
"status": "OPEN",
"opening_balance": { "currency": "USD", "amount": 0 },
"closing_balance": { "currency": "USD", "amount": -50.0 },
"revenues_total": { "currency": "USD", "amount": 100.0 },
"expenses_total": { "currency": "USD", "amount": -100.0 },
"payments_total": { "currency": "USD", "amount": -50.0 },
},
],
"pagination": { "total_records": 2, "type": "standard" },
}
/statement-period/{id}:
get:
summary: Get statement period by id.
parameters:
- in: path
name: id
description: ID of the statement period to get.
type: integer
required: true
responses:
200:
description: 200 OK
examples:
application/json:
{
"id": 1,
"name": "SP 1",
"vendor_id": 24601,
"created_date": "2022-04-05T06:07:08",
"updated_date": "2022-04-05T06:07:08",
"status": "OPEN",
"opening_balance": { "currency": "USD", "amount": 0 },
"closing_balance": { "currency": "USD", "amount": -50.0 },
"revenues_total": { "currency": "USD", "amount": 100.0 },
"expenses_total": { "currency": "USD", "amount": -100.0 },
"payments_total": { "currency": "USD", "amount": -50.0 },
}
/statement-period/close:
put:
summary: Closes a statement period.
parameters:
- in: body
name: data
description: Data to use when closing the statement period.
schema:
type: object
properties:
vendor_id:
type: integer
description: Vendor ID for which we're closing the open period.
responses:
200:
description: 200 OK
examples:
application/json:
{
"id": 2,
"name": null,
"vendor_id": 24601,
"created_date": "2022-04-05T06:07:08",
"updated_date": "2022-04-05T06:07:08",
"status": "OPEN",
}
/payments:
get:
summary: Get payments with paginated response and filters based on status.
parameters:
- in: query
name: vendor_id
description: array with the payment statuses as filter for the collaborator payments
type: integer
required: true
- in: query
name: payment_statuses
description: array with the payment statuses as filter for the collaborator payments
type: array
required: false
- in: query
name: limit
description: Limit for pagination.
type: integer
default: 0
required: false
- in: query
name: offset
description: Offset for pagination.
type: integer
default: 0
required: false
- in: query
name: sort_key
description: the key to sort the results with
type: string
required: false
- in: query
name: sort_direction
description: the direction of the sort filter (ASC or DESC)
type: string
required: false
responses:
200:
description: 200 OK
examples:
application/json:
{
"items":
[
{
"collaborator_id": 4,
"conversion_rate": None,
"created_date": "2020-05-04T03:02:01",
"id": 15,
"profile_id": 12341235,
"quote_id": "81b5e5b0-e7d8-4112-aad9-b9189d53dcb2",
"recipient_id": 22223333,
"source_amount": 40.0,
"source_currency": "USD",
"status": "incoming_payment_waiting",
"status_updated_date": "2020-05-04T03:04:01",
"target_amount": 40.0,
"target_currency": "USD",
"transfer_id": 15,
"transferwise_batch_id": 3,
"transferwise_fee": 0.25,
"wire_fee": 0.25,
},
{
"collaborator_id": 4,
"conversion_rate": None,
"created_date": "2020-05-04T03:02:01",
"id": 16,
"profile_id": 12341235,
"quote_id": "81b5e5b0-e7d8-4112-aad9-b9189d53dcb2",
"recipient_id": 22223333,
"source_amount": 40.0,
"source_currency": "USD",
"status": "cancelled",
"status_updated_date": "2020-05-04T03:04:01",
"target_amount": 40.0,
"target_currency": "USD",
"transfer_id": 16,
"transferwise_batch_id": 4,
"transferwise_fee": 0.25,
"wire_fee": 0.25,
},
],
"pagination": { "total_records": 2, "type": "standard" },
}
/transactions:
post:
summary: Create new transactions for the collaborators.
parameters:
- in: body
name: data
description: List of transactions to create.
schema:
type: array
items:
type: object
properties:
date:
type: string
description: Date for the transaction in ISO 8601 format.
type:
type: string
enum: ["REVENUE", "PAYMENT", "EXPENSE"]
description: Type of transaction to create.
original_amount:
type: number
description: Original amount of the transaction.
collaborator_share:
type: number
description: Collaborator's share.
description:
type: string
description: Description of the transaction.
report_id:
type: integer
description: ID of the report the transaction is for.
currency:
type: string
description: The currency in the form of ISO 4217
collaborator_id:
type: integer
description: The collaborator's unique identifier
required:
- date
- type
- original_amount
required: true
responses:
201:
description: 201 Created
examples:
application/json:
[
{
"id": 8,
"collaborator_id": 1,
"date": "2012-12-20",
"type": "PAYMENT",
"description": None,
"original_amount": -12.34,
"collaborator_share": None,
"chargeable_amount": -12.34,
"transferwise_transaction_id": None,
"report_id": None,
"created_date": "now",
"voided_transaction_id": None,
"currency": "USD",
"deleted_date": None,
"current_balance": 0,
"statement_period_id": 4,
},
{
"id": 9,
"collaborator_id": 2,
"date": "2012-12-20",
"type": "REVENUE",
"description": "A test",
"original_amount": 100.0,
"collaborator_share": 0.5,
"chargeable_amount": 50.0,
"transferwise_transaction_id": None,
"report_id": 4,
"created_date": "now",
"voided_transaction_id": None,
"currency": "USD",
"deleted_date": None,
"current_balance": 0,
"statement_period_id": 4,
},
]
400:
description: 400 Missing or empty body parameters
examples:
application/json:
{ "code": "missing_params", "message": "Missing param(s)" }
/statement-period/{statement_period_id}/transactions:
get:
summary: Get transactions for a statement period id.
parameters:
- in: query
name: limit
description: Limit for pagination.
type: integer
default: 0
required: false
- in: query
name: offset
description: Offset for pagination.
type: integer
default: 0
required: false
responses:
200:
description: 200 OK
examples:
application/json:
{
"items":
[
{
"chargeable_amount": 9001.0,
"collaborator_id": 20,
"collaborator_share": 1.0,
"created_date": "2020-02-03T04:05:06",
"currency": "USD",
"current_balance": 0,
"date": "2018-10-09",
"deleted_date": None,
"description": "Report revenue",
"id": 7,
"original_amount": 9001.0,
"report_id": 5,
"statement_period_id": 1,
"transferwise_transaction_id": 2,
"type": "CREDIT",
"voided_transaction_id": None,
},
{
"chargeable_amount": -100.0,
"collaborator_id": 1,
"collaborator_share": 1.0,
"created_date": "2019-11-10T09:08:07",
"currency": "USD",
"current_balance": 0,
"date": "2019-11-10",
"deleted_date": None,
"description": "Expense",
"id": 3,
"original_amount": -100.0,
"report_id": None,
"statement_period_id": 1,
"transferwise_transaction_id": None,
"type": "EXPENSE",
"voided_transaction_id": None,
},
],
"pagination": { "total_records": 2, "type": "standard" },
}
/products:
get:
summary: Get product ids for account with split filters.
parameters:
- in: query
name: vendor_id
description: Vendor's unique identifier.
type: integer
required: true
- in: query
name: limit
description: Limit for pagination.
type: integer
default: 0
required: false
- in: query
name: offset
description: Offset for pagination.
type: integer
default: 0
required: false
- in: query
name: min_tracks_with_splits
description: Minimum number of tracks with splits.
type: integer
required: false
- in: query
name: max_tracks_with_splits
description: Maximum number of tracks with splits.
type: integer
required: false
- in: query
name: min_tracks_without_splits
description: Minimum number of tracks without splits.
type: integer
required: false
- in: query
name: max_tracks_without_splits
description: Maximum number of tracks without splits.
type: integer
required: false
- in: query
name: term
description: Search term to match against product name or UPC
type: string
required: false
- in: query
name: label_participant_uuids
description: Comma separated list of label participant UUIDs
type: string
required: false
- in: query
name: subaccount_id
description: ID of subaccount to filter by
type: integer
required: false
- in: query
name: sort_key
description: The key to sort the results with
type: string
required: false
- in: query
name: sort_direction
description: The direction in which to sort results (ASC or DESC)
type: string
required: false
responses:
200:
description: 200 OK
examples:
application/json:
{
"items": [{ "product_id": 123 }, { "product_id": 456 }],
"pagination": { "total_records": 2, "type": "standard" },
}
/products/counts-dataloader:
post:
summary: Get counts for products by ID.
parameters:
- in: body
name: product_ids
description: List of product IDs
schema:
type: array
items:
type: int
required: true
responses:
200:
description: 200 OK
examples:
application/json:
[
{
"data":
{
"product_id": 322222,
"splits_count": 5,
"collaborators_count": 5,
"tracks_with_splits_count": 5,
},
},
{ "data": null },
]
/terms-and-conditions:
get:
summary: Gets terms and conditions info.
parameters:
- in: query
name: vendor_id
description: the account unique identifier
type: string
required: true
responses:
200:
description: 200 OK
examples:
application/json:
{
"latest_version": 1,
"latest_template": "Title
{{brand}}
",
"agreed_version": 2,
"agreed_date": "2006-05-04T03:02:01",
}
/terms-and-conditions/agreement:
post:
summary: Agrees a given version of terms and conditions document.
parameters:
- in: body
name: vendor_id
description: the account unique identifier
type: string
required: true
- in: body
name: terms_and_conditions_id
description: the version of the terms and conditions document
type: integer
required: true
responses:
200:
description: 200 OK
examples:
application/json:
{
"id": 1,
"terms_and_conditions_id": 1,
"vendor_id": 12345,
"vendor_brand": "theorchard",
"agreed_date": "2024-11-19T13:45:03",
"user_id": "abc-123",
}