Legal Entities

Important notes: Replace placeholders in URL examples to your values.

  • CLIENT_TYPE is customers or vendors

  • CLIENT_ID is your primary client id which is parent object of legal entity.

Example: /v1/customers/42/legal-entities

Fields summary

Field

Type

Read

Write

Filter

Order

Default

Req. for new

id

primary

client_id

int

client_type

string

is_primary

boolean

0

currency

string

payment_method

enum

data

object

sps_id

string

null

Available options

Field: payment_method

Legal entity type.

Option

Description

Check

Legal entity for Check payment method.

DirectDeposit

Legal entity for Direct Deposit payment method.

ePayments

Legal entity for ePayments payment method.

Payoneer

Legal entity for Payoneer payment method.

PayPal

Legal entity for PayPal payment method.

WebMoney

Legal entity for WebMoney payment method.

Wire

Legal entity for Wire payment method.

Complex fields

Field: data

Specific fields for legal entity. List depends on payment_method.

If payment_method is Check

Key

Required

Type

Description

data[payable_to]

string

The name of the person or company the check should be payable to

data[address1]

string

The first line of the payee address

data[address2]

string

The second line of the payee address

data[city]

string

The payee city

data[country]

string

The payee country

data[region]

string

The payee state/province

data[zipcode]

string

The payee zipcode / postal code

data[is_individual]

boolean

Whether or not the payee is an individual

If payment_method is DirectDeposit

Key

Required

Type

Description

data[account_holder]

string

Account Holder

data[account_number]

string

Account Number

data[bank_name]

string

Bank Name

data[other_details]

string

Other details

data[routing_number]

string

Routing Number

data[checked_by_manager]

string

Checked by Manager

If payment_method is ePayments

Key

Required

Type

Description

data[epayment_details]

string

ePayment wallet. Ex: 123-456789

If payment_method is Payoneer

Key

Required

Type

Description

data[payoneer_status]

string

Status in HasOffers

data[payoneer_email]

string

Email

If payment_method is WebMoney

Key

Required

Type

Description

data[webmoney_details]

string

Wallet (WMID)

If payment_method is PayPal

Key

Required

Type

Description

data[paypal_email]

email

paypal_email

If payment_method is Wire

Key

Required

Type

Description

data[beneficiary_name]

string

Beneficiary Name

data[account_number]

string

Account Number

data[routing_number]

string

Routing Number

data[bank_name]

string

Bank Name

data[bank_address]

string

Bank Address

data[bank_code]

string

Bank Code

data[bank_details]

string

Bank Details

data[bank_tax_id]

string

Bank Tax ID

data[billing_address]

string

Billing Address

data[branch_name]

string

Branch Name

data[contact_email]

string

Contact Email

data[corr_account]

string

Corr Account

data[phone]

string

Phone

data[reg_number]

string

Reg Number

data[signee]

string

Signee

data[state_of_incorporation]

string

State Of Incorporation

data[swift]

string

SWIFT

data[tax_id]

string

Tax ID

data[tax_mode]

string

Tax Mode

data[type]

string

Type

data[vat]

boolean

VAT Applicable

data[other_details]

string

Other Details

data[is_individual]

boolean

Is Individual

get
Get list by parent

https://api.CLIENT_ID.item8.io/v1/CLIENT_TYPE/CLIENT_ID/legal-entities/list
Find list of Legal entity by parent ID.
Request
Response
Headers
Item8-Api-Key
required
string
Authentication API key.
200: OK
{
"status": "success",
"message": "",
"data": [
{
"id": 42,
"client_id": 20,
"client_type": "Customer",
"is_primary": 1,
"currency": "USD",
"payment_method": "PayPal",
"data": {
"paypal_email": "john.smith@example.com"
},
"sps_id": "1q2w3e4r5t6y"
}
]
}
403: Forbidden
If you don't have an access.
{
"status": "forbidden",
"message": "You don't have an access to list action.",
"data": []
}

get
Get by ID

https://api.CLIENT_ID.item8.io/v1/CLIENT_TYPE/CLIENT_ID/legal-entities/:id
Find any legal-entity by id.
Request
Response
Path Parameters
id
required
int
Unique primary identifier of item8 object.
Headers
Item8-Api-Key
required
string
Authentication API key.
200: OK
{
"status": "success",
"message": "",
"data": {
"id": 42,
"client_id": 20,
"client_type": "Customer",
"is_primary": 1,
"currency": "USD",
"payment_method": "PayPal",
"data": {
"paypal_email": "john.smith@example.com"
},
"sps_id": "1q2w3e4r5t6y"
}
}
403: Forbidden
If you don't have an access.
{
"status": "forbidden",
"message": "You don't have an access to Legal entity.",
"data": []
}
404: Not Found
If legal-entity doesn't exist.
{
"status": "error",
"message": "Legal entity with id=42 not found.",
"data": []
}

post
Create

https://api.CLIENT_ID.item8.io/v1/CLIENT_TYPE/CLIENT_ID/legal-entities
Request to create new legal-entity in item8.
Request
Response
Headers
Item8-Api-Key
required
string
Authentication API key.
Form Data Parameters
client_id
required
integer
Parent object ID (vendors.id | customer.id).
client_type
required
string
Parent object type (Customer, Vendor).
is_primary
optional
integer
It is default legal entity for bills or invoices. Only one legal entity can be primary for parent object (vendor/customer).
currency
required
string
Currency of payment method.
payment_method
required
string
Legal entity type. Use only available options, see above.
data
required
object
Specific fields for legal entity. List depends on payment_method. Use only available keys, see above.
sps_id
optional
string
Unique legal entity ID in your tracking system (ONLY for Affise).
200: OK
Legal entity has been created and you get the data as it is stored in item8.
{
"status": "success",
"message": "New legal-entity created.",
"data": {
"id": 42,
"client_id": 20,
"client_type": "Customer",
"is_primary": 1,
"currency": "USD",
"payment_method": "PayPal",
"data": {
"paypal_email": "john.smith@example.com"
},
"sps_id": "1q2w3e4r5t6y"
}
}
403: Forbidden
If you don't have an access.
{
"status": "forbidden",
"message": "You don't have an access to create action.",
"data": []
}

put
Update

https://api.CLIENT_ID.item8.io/v1/CLIENT_TYPE/CLIENT_ID/legal-entities/:id
Request to update existing legal-entity in item8.
Request
Response
Path Parameters
id
required
int
Unique primary identifier of item8 object.
Headers
Item8-Api-Key
required
string
Authentication API key.
Form Data Parameters
is_primary
optional
integer
It is default legal entity for bills or invoices. Only one legal entity can be primary for parent object (vendor/customer).
currency
optional
string
Currency of payment method.
data
optional
object
Specific fields for legal entity. List depends on payment_method. Use only available keys, see above.
sps_id
optional
string
Unique legal entity ID in your tracking system (ONLY for Affise).
200: OK
Legal entity has been updated and you get data as it is stored in item8.
{
"status": "success",
"message": "Legal entity updated successfully.",
"data": {
"id": 42,
"client_id": 20,
"client_type": "Customer",
"is_primary": 1,
"currency": "USD",
"payment_method": "PayPal",
"data": {
"paypal_email": "john.smith@example.com"
},
"sps_id": "1q2w3e4r5t6y"
}
}
403: Forbidden
If you don't have an access.
{
"status": "forbidden",
"message": "You don't have an access to update action.",
"data": []
}
500: Internal Server Error
Validator finds some problem in your request.
{
"status": "error",
"message": "Email is not valid.",
"data": []
}

delete
Delete

https://api.CLIENT_ID.item8.io/v1/CLIENT_TYPE/CLIENT_ID/legal-entities/:id
Delete existing legal-entity from item8.
Request
Response
Path Parameters
id
required
int
Unique primary identifier of item8 object.
Headers
Item8-Api-Key
required
string
Authentication API key.
Form Data Parameters
reason
optional
string
Reason why you delete legal-entity Item8 saves the message in history. It should be empty or minimum 6 chars.
200: OK
Legal entity has been deleted.
{
"status": "success",
"message": "Legal entity deleted successfully.",
"data": []
}
403: Forbidden
If you don't have an access.
{
"status": "forbidden",
"message": "You don't have an access to delete action.",
"data": []
}
500: Internal Server Error
if validator finds some problem in your request.
{
"status": "error",
"message": "Message of reason should be minimum 6 letters.",
"data": []
}