Advertisers

Fields summary

Field

Type

Read

Write

Filter

Order

Default

Req. for new

id

primary

int

name

email

string

status

enum

list

Draft

email

email

string

phone

string

string

address

object

create_date

datetime

range

now

account_manager_id

users.id | null

int

sales_manager_id

users.id | null

int

null

net

enum

list

Net 30

billing_frequency

enum

list

Monthly

stats_type

enum

Tracking

sps_id

string

null

Available options

Field: status

Current state of Advertiser. You can change it only via API methods.

Option

Description

Active

Advertiser is ready to work.

Draft

Manager have to check and activate the Advertiser.

Blocked

Advertiser was blocked and does not work temporarily.

Deleted

Advertiser was deleted and is not visible in web UI.

Field: net

Payment term

Option

Description

Net 7

Written on an invoice to show that it must be paid within 7 days

Net 10

Written on an invoice to show that it must be paid within 10 days

Net 15

Written on an invoice to show that it must be paid within 15 days

Net 30

Written on an invoice to show that it must be paid within 30 days

Net 45

Written on an invoice to show that it must be paid within 45 days

Net 60

Written on an invoice to show that it must be paid within 60 days

Net 90

Written on an invoice to show that it must be paid within 90 days

Field: billing_frequency

Relevant only if stats_type is Tracking.

Option

Description

None

Disable

Weekly

Item8 creates Invoices weekly for the previous week.

Bi-Monthly

Item8 creates Invoices twice a month: for the first and the second half of month (1-15; 16-last day)

Monthly

Item8 creates Invoices monthly.

Field: stats_type

Source of billing statistics: tracking system or custom statistics entered manually.

Option

Description

Tracking

Item8 automatically creates Invoices basing on tracking statistics. The billing period is taken from billing_frequency

Custom

Statistics (conversions) can be uploaded to item8 by API but manager have to create Invoices manually.

Complex fields

Field: address

Address of person/company.

Key

Required

Type

Description

address[Country]

string

Name/code of country

address[State]

string

Name/code of state/region

address[City]

string

City name

address[Street]

string

Address - street and house number

address[Postcode]

string

Postcode (zipcode)

get
Filter

https://api.CLIENT_ID.item8.io/v1/customers
You can use filter conditions. See fields table above and documentation about item8 filters.
Request
Response
Headers
Item8-Api-Key
required
string
Authentication API key.
Query Parameters
filter
optional
object
Filter conditions. See field map above.
pagination
optional
object
Limit and page of filter result.
order
optional
object
Order by some field (asc|desc). See field map above.
200: OK
List of objects found in item8 by filter conditions. "data" will be empty if no objects match the conditions.
{
"status": "success",
"message": "",
"data": [
{
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"sps_id": "1q2w3e4r5t6y"
}
]
}
403: Forbidden
If you don't have an access.
{
"status": "forbidden",
"message": "You don't have an access to filter action.",
"data": []
}

get
Get by ID

https://api.CLIENT_ID.item8.io/v1/customers/:id
Find any customer 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,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"sps_id": "1q2w3e4r5t6y"
}
}
403: Forbidden
If you don't have an access.
{
"status": "forbidden",
"message": "You don't have an access to Customer.",
"data": []
}
404: Not Found
If customer doesn't exist.
{
"status": "error",
"message": "Customer with id=42 not found.",
"data": []
}

post
Create

https://api.CLIENT_ID.item8.io/v1/customers
Request to create new customer in item8.
Request
Response
Headers
Item8-Api-Key
required
string
Authentication API key.
Form Data Parameters
name
required
string
Advertiser person/company name.
email
required
string
Advertiser email for notification
phone
optional
string
Contact phone.
address
optional
object
Address of person/company. Use only available keys, see above.
account_manager_id
required
string
Network employee assigned as Advertiser's account manager. Account manager works with Advertiser's conversions, Invoices, agreements, legal entities and receives email notifications about them.
sales_manager_id
optional
string
Network employee assigned as Advertiser's sales manager. Sales manager works with Advertiser's agreements, legal entities and receives email notifications about them.
net
optional
string
Payment term. Use only available options, see above.
billing_frequency
optional
string
Relevant only if stats_type is Tracking. Use only available options, see above.
stats_type
optional
string
Source of billing statistics: tracking system or custom statistics entered manually. Use only available options, see above.
sps_id
optional
string
Unique Advertiser ID in your tracking system.
200: OK
Customer has been created and you get the data as it is stored in item8.
{
"status": "success",
"message": "New customer created.",
"data": {
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"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/customers/:id
Request to update existing customer 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
name
optional
string
Advertiser person/company name.
email
optional
string
Advertiser email for notification
phone
optional
string
Contact phone.
address
optional
object
Address of person/company. Use only available keys, see above.
account_manager_id
optional
string
Network employee assigned as Advertiser's account manager. Account manager works with Advertiser's conversions, Invoices, agreements, legal entities and receives email notifications about them.
sales_manager_id
optional
string
Network employee assigned as Advertiser's sales manager. Sales manager works with Advertiser's agreements, legal entities and receives email notifications about them.
net
optional
string
Payment term. Use only available options, see above.
billing_frequency
optional
string
Relevant only if stats_type is Tracking. Use only available options, see above.
stats_type
optional
string
Source of billing statistics: tracking system or custom statistics entered manually. Use only available options, see above.
sps_id
optional
string
Unique Advertiser ID in your tracking system.
200: OK
Customer has been updated and you get data as it is stored in item8.
{
"status": "success",
"message": "Customer updated successfully.",
"data": {
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"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": []
}

put
Block

https://api.CLIENT_ID.item8.io/v1/customers/:id/block
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 block the Advertiser. Item8 saves the message in history. It should be empty or minimum 6 chars.
200: OK
Advertiser blocked.
{
"status": "success",
"message": "",
"data": {
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"sps_id": "1q2w3e4r5t6y"
}
}

put
Unblock

https://api.CLIENT_ID.item8.io/v1/customers/:id/unblock
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 unblock the Advertiser. Item8 saves the message in history. It should be empty or minimum 6 chars.
200: OK
Advertiser unblocked.
{
"status": "success",
"message": "",
"data": {
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"sps_id": "1q2w3e4r5t6y"
}
}

put
Activate

https://api.CLIENT_ID.item8.io/v1/customers/:id/activate
Move Advertiser from Draft to Active status.
Request
Response
Path Parameters
id
required
int
Unique primary identifier of item8 object.
Headers
Item8-Api-Key
required
string
Authentication API key.
200: OK
Advertiser activated and ready to work.
{
"status": "success",
"message": "",
"data": {
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"sps_id": "1q2w3e4r5t6y"
}
}

put
Restore

https://api.CLIENT_ID.item8.io/v1/customers/:id/restore
Move Advertiser from Deleted to Draft status.
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 restore Advertiser from deleted. Item8 saves the message in history. It should be empty or minimum 6 chars.
200: OK
Advertiser restored.
{
"status": "success",
"message": "",
"data": {
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"sps_id": "1q2w3e4r5t6y"
}
}

delete
Delete

https://api.CLIENT_ID.item8.io/v1/customers/:id
Delete existing customer 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 customer Item8 saves the message in history. It should be empty or minimum 6 chars.
200: OK
Customer has been deleted.
{
"status": "success",
"message": "Customer 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": []
}