MyServe API Documentation

Start with Getting started: it covers hosts, authentication, errors and the sandbox flag. Each section after it documents one part of the API.

Getting started

The MyServe customer API lets your systems read and update the devices, employees, accounting categories, wirelines, orders and requests your organisation manages in MyServe. This page covers what every call has in common; the Workflows page shows the order to call things in, and the Glossary explains the terms.

Hosts and versions

Use the host of the MyServe site your organisation signs in to:

Name	Value
Organisations on myserve.ca	https://myserve.ca/api/v1/clients
Organisations on myserve.co	https://myserve.co/api/v1/clients

v1 is the only version. The same endpoints also answer without it (/api/clients/...); this documentation always shows /api/v1/clients/....

Authentication

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX https://myserve.co/api/v1/clients/devices

Fail Response

{
  "message": "Invalid API token provided"
}

{
  "message": "Not allowed IP"
}

Send your organisation's API token in the API_TOKEN header of every request. In MyServe, open your organisation's Settings, then Integration settings, to see the token or regenerate it. Regenerating it stops the old token from working at once.

On the same page you can list the IP addresses allowed to call the API. When the list is empty, any address may call; when it is not, calls from other addresses are refused.

A missing or wrong token answers with HTTP status 200 and {"message": "Invalid API token provided"}; a caller address that is not on the list answers with HTTP status 200 and {"message": "Not allowed IP"}. Check the body, not only the status code.

Request and response conventions

Every endpoint takes and returns JSON in UTF-8.

• Send Content-Type: application/json with every POST request; GET parameters go in the URL query string.
• Lists are returned in a data array. Requests that create something return the new record, or its id or uuid, to use with the matching GET endpoint.
• Where a list is paginated, pass page (100 items per page). The orders, cities and ZIP codes lists then also return total_count, page and total_pages; the employees list returns only data. Without page, the employees and orders lists return every record.
• Several lists accept since, a Unix time in seconds, to return only what changed after that moment.
• Synchronization requests run while you wait unless you send async: true or more than 300 rows; then they return a job_id to poll with the matching synchronization status endpoint.

Errors

MyServe answers with these HTTP status codes:

Name	Description
200	Success, and also a refused request: the body is then only a message key (invalid token, caller address not allowed, invalid sandbox value, or a missing report or job). A successful synchronization also carries a message, next to its job_id.
201	A device request, order, ticket or transfer was created.
403	The synchronization job you asked about belongs to another organisation.
404	The record was not found; the JSON body says which (for example {"message": "Business account not found"} or {"status": "failed", "error": "Ticket not found"}).
422	The request was understood but rejected; the body lists the reasons. An identical request sent while the first one is still being processed answers 422 and creates nothing; the message in the body says so, next to "status": "failed" for an order or a transfer request. These endpoints: Create hardware order, Create new SIM card change request, Create Transfer In Request, Create Transfer Out Request, Create new ticket, Change device status. A request that fails inside MyServe answers 422 with {"error": "The request could not be processed.", "reference": 1234} (an order or a transfer request also adds "status": "failed"); give the reference to support so they can find what happened. This can happen on these endpoints: Create hardware order, Create new SIM card change request, Create Transfer In Request, Create Transfer Out Request, Create new ticket, Change device status.
429	A synchronization of the same kind is still running for your organisation; wait and try again.

429 Too Many Requests

{
  "message": "Too many requests"
}

422 Unprocessable Entity

{
  "status": "failed",
  "errors": ["can't create order for the carrier"]
}

Each endpoint section lists the exact bodies it can return.

The sandbox flag

Invalid sandbox value

{
  "message": "sandbox attribute should have a Boolean value"
}

The synchronization endpoints and the transfer of responsibility requests accept sandbox. With sandbox: true MyServe checks every row and reports what it would do, but changes nothing. Synchronizations answer as usual with the per-row results; a valid transfer of responsibility answers with HTTP status 422 and "request is correct but was not saved because of sandbox parameter".

On the synchronization endpoints sandbox must be true or false; any other value is refused with the message shown here, except on the devices synchronization, which reads any other value as true or false. The transfer of responsibility requests do not check the value: only true (or "true", "t") means sandbox, and any other value creates a real request.

Your first call

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX https://myserve.co/api/v1/clients/devices

Success Response

{
  "data": [
    {
      "username": "Jane Doe",
      "number": "7805550123",
      "status": "active"
    }
  ]
}

List your devices. An HTTP 200 answer with a data array means the token and your caller address are accepted.

Last verified against MyServe on 2026-10-16.

Workflows

Each workflow below lists the calls to make, in order, with a link to the endpoint's section.

Connect for the first time

Do this once, before anything else, to prove that your token and network are set up.

Before you start: Your organisation has a MyServe account and someone with access to its Integration settings.

1. Copy the API token from Integration settings, and add your servers' addresses to the IP allow-list if you use one. (Authentication)
2. List your devices: GET /api/v1/clients/devices (Your first call)
3. If the answer has a message key, read it against the error list. (Errors)

How you know it is done: The answer is HTTP 200 with a data array and no message key.

Keep MyServe in sync with your systems

Use this to push your HR, finance and inventory data into MyServe, for example every night.

Before you start: The accounting types, business accounts and wireline accounts you refer to already exist in MyServe; the synchronizations do not create them.

1. Send your employees first: devices refer to employee numbers, and approval managers of accounting categories are employees. POST /api/v1/clients/employees/synchronize (Synchronize lists of employees)
2. Send your accounting categories next: devices refer to category names. POST /api/v1/clients/accounting_categories/synchronize (Synchronize lists of accounting categories)
3. Send your devices and your wirelines: POST /api/v1/clients/devices/synchronize (Synchronize lists of devices), POST /api/v1/clients/wirelines/synchronize (Synchronize lists of wirelines)
4. If you sent async: true or more than 300 rows, poll the matching synchronization status endpoint with the job_id you received (devices shown; employees, accounting categories and wirelines have their own): POST /api/v1/clients/devices/synchronization_status (Check devices synchronization job status)
5. Optionally read back what changed: GET /api/v1/clients/devices?since=... (Get list of customer devices)

How you know it is done: A synchronous request answers with a results entry per row, and "Successfully performed" only when every row succeeded; if any row failed it answers "Errors occurred during the perform". For an asynchronous one, poll until status is completed (every row succeeded) or errored (at least one row failed); created and performing mean it is still running. Each row is reported on its own: a rejected row does not stop the rows after it, and rows with status: error carry their errors. Try a run with sandbox: true first to see the results without changing anything.

Order hardware

Use this to order a new device, a replacement or accessories through your carrier's dealer.

Before you start: Hardware ordering is turned on for your organisation, with at least one carrier you can order from, a dealer for it, and the business account, employee and accounting categories you will name.

1. List the products you can order from the carrier: GET /api/v1/clients/hardware_ordering/products?carrier=Bell (Get list of customer products)
2. List the accessories, optionally for one product: GET /api/v1/clients/hardware_ordering/accessories?product_id=... (Get list of customer accessories)
3. Look up the city id (Canada) or the ZIP code (United States) for each line: GET /api/v1/clients/hardware_ordering/cities (Get list of Canadian cities), GET /api/v1/clients/hardware_ordering/zip_codes (Get list of ZIP codes)
4. Create the order: POST /api/v1/clients/orders (Create hardware order)
5. Read the order to follow its state: GET /api/v1/clients/orders/<order-uuid> (Get hardware order information)

How you know it is done: The create call answers HTTP 201 with status "succeeded". The order's state then moves on in MyServe; it is final when it is "Completed" or "Cancelled".

Change a SIM card

Use this when a line needs a new physical SIM card. The API cannot request an eSIM.

Before you start: The device exists in MyServe and has no open SIM card change for the same old and new SIM.

1. Create the request with the line number and the new SIM number: POST /api/v1/clients/device_requests/sim_card_changes (Create new SIM card change request)
2. Read the request with the id you received: GET /api/v1/clients/device_requests/sim_card_changes/:id (Get status of SIM card change request)

How you know it is done: The status is finished or canceled; initial and started mean it is still in progress.

Transfer a line in or out

Use this when a person or another business hands a line over to your organisation (in), or when you hand one of your lines to a person or another business (out).

Before you start: For a transfer in, the business account and the rate plan (or a default rate plan for the device make) exist in MyServe. For a transfer out, the line is one of your devices.

1. To bring a line in: POST /api/v1/clients/device_requests/transfer_of_responsibility/to_business (Create Transfer In Request)
2. To hand a line out: POST /api/v1/clients/device_requests/transfer_of_responsibility/from_business (Create Transfer Out Request)
3. Read the request with the uuid you received: GET .../to_business/:uuid (Get Transfer In Request), GET .../from_business/:uuid (Get Transfer Out Request)

How you know it is done: The status is completed, declined or cancelled (a transfer out to a person ends as completed or cancelled); other values mean it is still in progress.

Raise a ticket

Use this to ask the MyServe team for something no other endpoint covers.

Before you start: Nothing beyond a working token.

1. Create the ticket: POST /api/v1/clients/tickets (Create new ticket)
2. Read it with its id, or list the tickets changed since your last check: GET /api/v1/clients/tickets/:id (Get ticket data), GET /api/v1/clients/tickets?since=... (Get list of tickets)

How you know it is done: The status is completed or cancelled; pending means the team has not closed it yet.

Report on usage and billing

Use this to bring usage and cost data into your own reporting.

Before you start: MyServe has received usage from your carriers and processed at least one bill for the cycle you ask for.

1. For usage so far this cycle, read it per device or per pooled business account: GET /api/v1/clients/in_month_data_usage/by_number (Get device In Month data usage), GET /api/v1/clients/in_month_data_usage/business_accounts (Get business accounts In Month data usage)
2. For billed data usage per device on one business account: GET /api/v1/clients/data_usage/by_business_account (Get devices current month data usage by business account)
3. For every charge on a processed bill, read the billing data lines for its cycle date, page by page: GET /api/v1/clients/billing_data_lines?cycle_date=... (Get list of device billing data lines)
4. If MyServe has set up an accounting report format for your organisation, read the allocation entries for one bill: POST /api/v1/clients/reports/accounting (Get the accounting report for a bill)

How you know it is done: Billing data lines answer 100 lines per page and do not say how many pages there are: keep reading the next page until one comes back with fewer than 100 lines or none. The other reports answer in a single call.

Devices API

A device is a mobile line (a phone number) that your organisation manages in MyServe. Use these endpoints to read your devices, to keep MyServe in step with your own system, and to ask the carrier to suspend or cancel a line.

Get list of customer devices

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX "https://myserve.co/api/v1/clients/devices?since=1760572800"

Success Response

{
  "data": [
    {
      "username": "Jane Doe",
      "number": "7805550123",
      "customer_id": "26",
      "device_id": "18255698",
      "status": "active",
      "device_make_and_model": "iPhone iPhone 15",
      "device_make": "iPhone",
      "device_make_name": "iPhone",
      "device_email": "jane.doe@example.com",
      "manager": ["John Smith"],
      "carrier": "Bell",
      "device_location": "Edmonton",
      "employee_number": "0123456789",
      "contract_expiry_date": "2027-03-31",
      "contract_balance": "Unknown",
      "imei_number": "356789012345678",
      "sim_number": "8930212345678901234",
      "static_ip": null,
      "asset_tag": "34567",
      "account_number": "121212",
      "device_upgrade_cost": "123",
      "last_upgraded_date": "2025-01-01",
      "device_model_id": 1,
      "device_used_for": "Field work",
      "device_initial_activation_date": "2024-01-15",
      "device_contract_start_date": "2024-01-15",
      "rate_plans": "Business Unlimited",
      "transfer_responsibility_etf": "12.24",
      "evergreen_date": "2027-03-31",
      "eligibility_date": "2026-01-15",
      "redeployment_available": false,
      "accounting_type_5402": ["Executive"],
      "directory_push": true
    }
  ]
}

Fail Response

{
  "message": "Invalid API token provided"
}

HTTP Request

GET: /api/v1/clients/devices

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
since	URL	Integer	False	Return only devices changed after this time, in Unix time (seconds).

Query Response

Type: JSON

HTTP status code: 200 on success, and also 200 with a message when the request is refused (invalid API token or caller address not allowed).

Success Response

Name	Type	Description
data	Array	Array of devices
data[0][username]	String	Name of the person who uses the device
data[0][number]	String	Phone number of the device
data[0][customer_id]	String	Id of your organisation in MyServe
data[0][device_id]	String	Id of the device in MyServe
data[0][status]	String	Device status, "active", "suspended" or "cancelled"
data[0][device_make_and_model]	String	Device make followed by device model
data[0][device_make]	String	Device make
data[0][device_make_name]	String	Device make name (same value as device_make)
data[0][device_email]	String	Email address
data[0][manager]	Array	Array with one item, First and Last name of the manager
data[0][carrier]	String	Carrier name
data[0][device_location]	String	Location of the device
data[0][employee_number]	String	Employee number
data[0][contract_expiry_date]	String	Contract expiration date
data[0][contract_balance]	String	Remaining contract balance, or "Unknown"
data[0][imei_number]	String	Device IMEI number
data[0][sim_number]	String	Sim number
data[0][static_ip]	String	IP address
data[0][asset_tag]	String	Your asset tag for the device
data[0][account_number]	String	Number of the business account the device belongs to
data[0][device_upgrade_cost]	String	Upgrade cost
data[0][last_upgraded_date]	String	Last upgrade date
data[0][device_model_id]	Integer	Id of device model
data[0][device_used_for]	String	Used for
data[0][device_initial_activation_date]	String	Initial activation date
data[0][device_contract_start_date]	String	Contract start date
data[0][rate_plans]	String	Rate plans
data[0][transfer_responsibility_etf]	String	Transfer Responsibility ETF
data[0][evergreen_date]	String	Evergreen date
data[0][eligibility_date]	String	Eligibility Date
data[0][redeployment_available]	Boolean	Redeployment Available
data[0][accounting_type_<id>]	Array	One key per accounting type of your organisation, named accounting_type_ followed by the type's id; the value lists the device's category names for that type.
data[0][directory_push]	Boolean	Directory push

Fail Response

Name	Type	Description
message	String	Why the request was refused, for example "Invalid API token provided" or "Not allowed IP"

Synchronize lists of devices

Example:

curl -d "{\"sandbox\": true, \"data\": [{\"number\":\"7805550123\", \"username\":\"Doe, Jane\", \"billing_account\":\"121212\", \"device_make\":\"iPhone\", \"email\":\"jane.doe@example.com\", \"employee_number\":\"0123456789\", \"manager\":\"John Smith\", \"status\":\"active\", \"accounting_categories\":[{\"Department\":\"Executive\",\"percent\":\"100\"}]}]}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/devices/synchronize

Success Response (sync)

{
  "message": "Successfully performed",
  "job_id": 134,
  "results": {
    "7805550123": {
      "status": "updated"
    },
    "7805550124": {
      "status": "created"
    }
  }
}

Fail Response (sync)

{
  "message": "Errors occurred during the perform",
  "job_id": 135,
  "results": {
    "7805550123": {
      "status": "error",
      "errors": [
        "This manager doesn't exist on this customer"
      ]
    },
    "7805550124": {
      "status": "updated"
    }
  }
}

Success Response (async)

{
  "message": "Job successfully created",
  "job_id": 136
}

Fail Response

{
  "message": "Too many requests"
}

HTTP Request

POST: /api/v1/clients/devices/synchronize

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
data	Body	Array	True	Array of devices
sandbox	Body	Boolean	False	Turn on/off sandbox mode. If sandbox mode turned on, then changes will not apply to the customer account.
async	Body	Boolean	False	Turn on/off async mode. If it is turned on, then perform synchronization asynchronously. Default: false. Requests with more than 300 rows always run asynchronously.

Available device attributes in data param

Name	Type	Required?	Description
number	String	True	Phone number of the device; used to find the device. Non-digits are removed.
username	String	TRUE for new devices	Name of the person who uses the device. “Last name, First name” will be transformed to “First name Last name” if value contains comma. A row for an existing device without it keeps the current name; a row for a new device without it fails with "Missing required data for new device".
billing_account	String	TRUE for new devices	Number of the business account the device belongs to. The account must already exist in MyServe; an unknown number is ignored and the device keeps its current account.
device_make	String	TRUE for new devices	Name of the maker
device_model	String	False	Name of the device model, as in MyServe
device_model_variant	String	False	Variant of the device model, for example the storage size
status	String	False	Device status, "active", "suspended" or "cancelled"
email	String	False	Email address
username_alias	String	False	Another name for the user
location	String	False	Location of the device
employee_number	String	False	Employee number
manager	String	False	First and Last name of the manager, as in MyServe
accounting_categories	Array	False	Array with hashes. Hash contains a pair of account type and account category with percent value, where key is a type name and value is a category name, 'percent' is a key for percent param. Sum of all percent values should be equal 100. The same array sent as a JSON string is also accepted.
asset_tag	String	False	Your asset tag for the device
imei_number	String	False	Device IMEI number
sim_number	String	False	SIM card number
eid_number	String	False	eSIM identifier (EID)
mac_address	String	False	MAC address
static_ip	String	False	Static IP address
private_apn_area	String	False	Private APN area
carrier_username	String	False	Name of the user as the carrier knows it
added_features	String	False	Features added to the line
used_for	String	False	Used for
supply_method	String	False	How the device was supplied, for example "COBO"
upgrade_cost	String	False	Upgrade cost
contract_current_balance	String	False	Remaining contract balance
initial_activation_date	String	False	Date in format yyyy-mm-dd
contract_start_date	String	False	Date in format yyyy-mm-dd
contract_expiry_date	String	False	Date in format yyyy-mm-dd
eligibility_date	String	False	Date in format yyyy-mm-dd
evergreen_date	String	False	Date in format yyyy-mm-dd
warranty_expiry_date	String	False	Date in format yyyy-mm-dd
last_upgraded_date	String	False	Date in format yyyy-mm-dd
directory_push	Boolean	False	Include the device in directory push
hr_locked	Boolean	False	When true, the device keeps its own accounting categories instead of taking its employee's
redeployment_available	Boolean	False	The device can be given to another user

Query Response

Type: JSON

HTTP status code: 200 on success and when some rows fail (see results), and 200 with a message when the request is refused; 429 while a previous synchronization for your organisation still holds the lock.

Response

Name	Type	Presence	Description
message	String	always	"Successfully performed", "Errors occurred during the perform" (see results) or "Job successfully created" (asynchronous or still running)
job_id	Integer	unless refused	ID of a created job (use it to get job status)
results	Hash	sync request only	Key - device number or 'Common' which means that this info doesn't connected with some device, value - hash with some info like status and maybe array of errors

Fail Response

Name	Type	Description
message	String	Why the request was refused: "Invalid API token provided", "Not allowed IP", "sandbox attribute should have a Boolean value" or "Too many requests" (HTTP 429)

Check devices synchronization job status

Example:

curl -d "{\"job_id\": \"134\"}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/devices/synchronization_status

Success Response (performing)

{
  "status": "performing",
  "results": {}
}

Success Response (completed)

{
  "status": "completed",
  "results": {
    "7805550123": {
      "status": "updated"
    }
  }
}

Fail Response

{
  "status": "errored",
  "results": {
    "7805550123": {
      "errors": [
        "This manager doesn't exist on this customer"
      ],
      "status": "error"
    }
  }
}

{
  "message": "Job not found"
}

HTTP Request

POST: /api/v1/clients/devices/synchronization_status

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
job_id	Body	Integer	True	Job ID

Query Response

Type: JSON

HTTP status code: 200, including when the job is not found; 403 when the job belongs to another organisation.

Name	Type	Description
status	String	Status of synchronization
results	Hash	Hash with results of synchronization; empty until the job has run

Fail Response

Name	Type	Description
message	String	"Job not found" (HTTP 200) or "Access forbidden" (HTTP 403, the job belongs to another organisation)

Change device status

Examples:

curl -d "{\"number\":\"7805550123\", \"new_status\":\"cancelled\"}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/devices/change_status
curl -d "{\"number\":\"7805550123\", \"new_status\":\"suspended\", \"new_status_details\": \"Full Rate\"}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/devices/change_status

Success Response

{ "id": 232910 }

Fail Response

{ "device_active_requests": ["must be blank"] }

HTTP Request

POST: /api/v1/clients/devices/change_status

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
number	Body	String	True	device number
new_status	Body	String	True	"cancelled" or "suspended"
new_status_details	Body	String	False	For a suspension: "Reduced Rate" or "Full Rate"
external_reference_number	Body	String	False	Your reference for this request

Query Response

Type: JSON

HTTP status code: 201 when the status change request is created; 422 when it is rejected.

Name	Type	Description
id	Integer	id of created status update request

Fail Response

A rejected request answers with HTTP status 422 and the reasons, keyed by field: number when the number is not one of your devices, device_active_requests when the line already has an open request, device (can't be blank) when number is blank, new_status (can't be blank) when new_status is missing, device (already <status>!) when the line already has that status. A request that fails inside MyServe answers 422 with {"error": "The request could not be processed.", "reference": 1234} (see Errors under Getting started).

Employees API

An employee is a person in your organisation who can be assigned devices and act as a manager or approver. Use these endpoints to read your employees and to keep MyServe in step with your HR system. Synchronize employees before devices, because devices refer to employee numbers.

Get list of customer employees

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX "https://myserve.co/api/v1/clients/employees?page=1&since=1527450237"

Success Response

{
  "data": [
    {
      "number": "A100500",
      "name": "Chuck N",
      "preferred_name": "Bruce L",
      "status": "active",
      "address": "Earth",
      "email": "gmail@chucknorris.com",
      "job_title": "Ranger",
      "hr_user_id": "0",
      "manager_name": "Nobody",
      "manager_employee_number": "12345",
      "department_name": "Texas Ranger Division",
      "accounting_categories":  [{
        "AccountingType1 Name": "AccountingCategory1 Name",
        "AccountingType2 Name": "AccountingCategory2 Name"
      }],
      "organization": "Hollywood",
      "terminated_date": "",
      "city": "Edmonton",
      "country": "Canada",
      "postalcode": "T5A 0A1",
      "province": "Alberta",
      "employee_type": "Full-Time Walker",
      "locale": "fr-CA",
      "meta": {
        "custom_field_1": "123456"
      },
      "secondary_manager_name": "Joe Nobody",
      "secondary_manager_employee_number": "0001234"
    }, {...}
  ]
}

Success Response

Name	Type	Description
data	Array	Array of employees
data[0][number]	String	Employee number
data[0][name]	String	Name
data[0][preferred_name]	String	Preferred name
data[0][status]	String	Status
data[0][address]	String	Address
data[0][email]	String	Email address
data[0][job_title]	String	Job title
data[0][hr_user_id]	String	HR user ID
data[0][manager_name]	String	Manager name
data[0][manager_employee_number]	String	Manager Employee Number
data[0][department_name]	String	Department name
data[0][accounting_categories][0][:accounting_type]	String	Key is accounting type name, value is accounting category name
data[0][organization]	String	Organization
data[0][terminated_date]	String	Terminated Date
data[0][city]	String	City
data[0][country]	String	Country
data[0][postalcode]	String	Zip Code / Postal Code
data[0][province]	String	State / Province
data[0][employee_type]	String	Employee type
data[0][locale]	String	Preferred language. 'en' or 'fr-CA'
data[0][meta]	Hash	Additional employee information. Can contain any key.
data[0][secondary_manager_name]	String	Secondary Manager Name
data[0][secondary_manager_employee_number]	String	Secondary Manager Employee Number

Fail Response

{
  "message": "Invalid API token provided"
}

HTTP Request

GET: /api/v1/clients/employees

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
page	URL	Integer	False	Page number, 100 employees per page. Without it, all employees are returned.
since	URL	Integer	False	Return only employees changed after this time, in Unix time (seconds).

Query Response

Type: JSON

HTTP status code: 200 on success, and also 200 with a message when the request is refused (invalid API token or caller address not allowed).

Fail Response

Name	Type	Description
message	String	Why the request was refused, for example "Invalid API token provided" or "Not allowed IP"

Synchronize lists of employees

Example:

curl -d "{\"data\":[{\"number\":\"A100500\",\"name\":\"Chuck N\",\"status\":\"active\",\"address\":\"Earth\",\"email\":\"gmail@chucknorris.com\",\"job_title\":\"Ranger\",\"organization\":\"Hollywood\"}]}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/employees/synchronize

Success Response (sync)

{
  "message": "Successfully performed",
  "job_id": 140,
  "results": {
    "A100500": {
      "status": "created"
    }
  }
}

Fail Response (sync)

{
  "message": "Errors occurred during the perform",
  "job_id": 141,
  "results": {
    "A100500": {
      "errors": [
        "This manager doesn't exist on this customer"
      ],
      "status": "error"
    }
  }
}

Success Response (async)

{
  "message": "Job successfully created",
  "job_id": 142
}

Fail Response

{
  "message": "sandbox attribute should have a Boolean value"
}

HTTP Request

POST: /api/v1/clients/employees/synchronize

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
data	Body	Array	True	Array of employees data
sandbox	Body	Boolean	False	Turn on/off sandbox mode. If sandbox mode turned on, then changes will not apply to the customer account.
async	Body	Boolean	False	Turn on/off async mode. If it is turned on, then perform synchronization asynchronously. Default: false. Requests with more than 300 rows always run asynchronously.
status_callback_url	Body	String	False	URL for async job result status callback as post query, (see employees synchronization result values attributes).

Available employee attributes in data param:

Name	Type	Required?	Can be blank?	Description
employee_number	String	True	False	Unique employee number; used to find the employee. The older name number is also accepted.
name	String	TRUE for new employees	False	“Last name, First name” will be transformed to “First name Last name” if value contains comma
preferred_name	String	False	True	Employee preferred name
email	String	False	TRUE for managers	Should be unique if not blank
status	String	False	True	Employee status: "active", "on_leave", "long_term", "short_term", "maternity_leave", "temp_layoff", "inactive", or a status your organisation has mapped in MyServe. Any other value is stored as "active".
hr_user_id	String	False	True	HR user ID
job_title	String	False	True	Job title
department_name	String	False	True	Department name
address	String	False	True	Address
hired_date	Integer	False	True	Hire date in Unix time (seconds)
terminated_date	Integer	False	True	Termination date in Unix time (seconds)
manager_name	String	False	True	First and Last name of the manager
manager_employee_number	String	False	True	Employee number of the manager. If both manager_name and manager_employee_number are present, then manager_employee_number will be used
accounting_categories	Array	False	True	Array with hashes. Hash contains a pair of account type and account category, where key is a type name and value is a category name.
is_manager	Boolean	False	True	If true, then the employee will be marked as manager as well
organization	String	False	True	Employee organization
city	String	False	True	City
country	String	False	True	Country
postalcode	String	False	True	Zip Code / Postal Code
province	String	False	True	State / Province
employee_type	String	False	True	Employee type
locale	String	False	True	Preferred language. 'en' or 'fr-CA'
meta	Hash	False	True	Additional employee information. Can contain any keys.
secondary_manager_employee_number	String	False	True	Secondary manager's employee number

Query Response

Type: JSON

HTTP status code: 200 on success and when some rows fail (see results), and 200 with a message when the request is refused; 429 while a previous synchronization for your organisation still holds the lock.

Name	Type	Presence	Description
message	String	always	"Successfully performed", "Errors occurred during the perform" (see results) or "Job successfully created" (asynchronous or still running)
job_id	Integer	unless refused	ID of created job
results	Hash	sync request only	Key - employee number, or 'Common' for an error not tied to one employee; value - hash with status (created, updated, error) and maybe array of errors

Fail Response

Name	Type	Description
message	String	Why the request was refused: "Invalid API token provided", "Not allowed IP", "sandbox attribute should have a Boolean value" or "Too many requests" (HTTP 429)

Check synchronization job status

Example:

curl -d "{\"job_id\": \"140\"}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/employees/synchronization_status

Success Response (performing)

{
  "status": "performing",
  "results": {}
}

Success Response (completed)

{
  "status": "completed",
  "results": {
    "A100500": {
      "status": "updated"
    }
  }
}

Fail Response

{
  "status": "errored",
  "results": {
    "A100500": {
      "errors": [
        "This manager doesn't exist on this customer"
      ],
      "status": "error"
    }
  }
}

{
  "message": "Job not found"
}

HTTP Request

POST: /api/v1/clients/employees/synchronization_status

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
job_id	Body	Integer	True	Job ID

Query Response

Type: JSON

HTTP status code: 200, including when the job is not found; 403 when the job belongs to another organisation.

Name	Type	Description
status	String	Status of synchronization
results	Hash	Hash with results of synchronization; empty until the job has run

Fail Response

Name	Type	Description
message	String	"Job not found" (HTTP 200) or "Access forbidden" (HTTP 403, the job belongs to another organisation)

Accounting Categories API

An accounting category is a cost-allocation label of your own (a cost centre, GL account or department), grouped under an accounting type. Devices and employees carry one category per type. Use these endpoints to read your categories and to keep them in step with your finance system; synchronize them before devices, because devices refer to category names.

Get list of customer accounting categories

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX https://myserve.co/api/v1/clients/accounting_categories

Success Response

{
  "data": [
    {
      "accounting_type": "GL Account",
      "name": "accounting category",
      "description": "first description",
      "description_2": "second description",
      "description_3": "third description",
      "description_4": "fourth description",
      "description_5": null,
      "description_6": null,
      "tax_jurisdiction": "tax jurisdiction",
      "additional_status": "additional status"
    },
    {
      "accounting_type": "GL Account 2",
      "name": "accounting category 2",
      "description": "first description",
      "description_2": "second description",
      "description_3": "third description",
      "description_4": "fourth description",
      "description_5": null,
      "description_6": null,
      "tax_jurisdiction": "tax jurisdiction",
      "additional_status": "additional status",
      "approval_managers": [
        {
          "employee_number": "0123456789",
          "name": "Mike Scott",
          "email": "mike@scott.com"
        }
      ]
    }
  ]
}

Fail Response

{
  "message": "Invalid API token provided"
}

HTTP Request

GET: /api/v1/clients/accounting_categories

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API

Query Response

Type: JSON

HTTP status code: 200 on success, and also 200 with a message when the request is refused (invalid API token or caller address not allowed).

Success Response

Name	Type	Description
data	Array	Array of accounting categories
data[0][accounting_type]	String	Accounting type name
data[0][name]	String	Accounting category name
data[0][description]	String	Free-text description; six are available
data[0][description_2]	String	Free-text description; six are available
data[0][description_3]	String	Free-text description; six are available
data[0][description_4]	String	Free-text description; six are available
data[0][description_5]	String	Free-text description; six are available
data[0][description_6]	String	Free-text description; six are available
data[0][tax_jurisdiction]	String	Tax jurisdiction of the category
data[0][additional_status]	String	Your own status for the category
data[0][approval_managers]	Array	Array of approval_managers. The attribute exists if accounting_type has this option.
data[0][approval_managers][0][employee_number]	String | null	Approval manager employee number
data[0][approval_managers][0][name]	String	Approval manager name
data[0][approval_managers][0][email]	String	Approval manager email

Fail Response

Name	Type	Description
message	String	Why the request was refused, for example "Invalid API token provided" or "Not allowed IP"

Synchronize lists of accounting categories

Example:

curl -d "{\"data\":[{\"accounting_type\":\"GL Account\",\"name\":\"12345\",\"description\":\"test\",\"description_2\":\"test_2\",\"description_3\":\"test_3\",\"description_4\":\"test_4\",\"tax_jurisdiction\":\"test\",\"additional_status\":\"status\"}]}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/accounting_categories/synchronize

Example with an approval manager:

curl -d "{\"data\":[{\"accounting_type\":\"Department\",\"name\":\"Sales\",\"description\":\"test\",\"description_2\":\"test_2\",\"description_3\":\"test_3\",\"description_4\":\"test_4\",\"tax_jurisdiction\":\"test\",\"additional_status\":\"status\", \"approval_managers\": [{\"name\": \"Mike Tyson\"}]}]}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/accounting_categories/synchronize

Success Response (sync)

{
  "message": "Successfully performed",
  "job_id": 154,
  "results": {
    "accounting category 1": {
      "status": "created",
      "accounting_type": "accounting type 1",
      "accounting_type_id": 1
    },
    "accounting category 2": {
      "status": "updated",
      "accounting_type": "accounting type 1",
      "accounting_type_id": 1
    }
  }
}

Fail Response (sync)

{
  "message": "Errors occurred during the perform",
  "job_id": 155,
  "results": {
    "accounting category 1": {
      "status": "error",
      "errors": [
        "This accounting type doesn't exist on this customer"
      ]
    },
    "accounting category 2": {
      "status": "error",
      "errors": [
        "Approval manager required"
      ]
    },
    "accounting category 3": {
      "status": "updated"
    }
  }
}

Success Response (async)

{
  "message": "Job successfully created",
  "job_id": 156
}

Fail Response

{
  "message": "Too many requests"
}

HTTP Request

POST: /api/v1/clients/accounting_categories/synchronize

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
data	Body	Array	True	Array of accounting categories
sandbox	Body	Boolean	False	Turn on/off sandbox mode. If sandbox mode turned on, then changes will not apply to the customer account.
async	Body	Boolean	False	Turn on/off async mode. If it is turned on, then perform synchronization asynchronously. Default: false. Requests with more than 300 rows always run asynchronously.
status_callback_url	Body	String	False	URL for async job result status callback as post query, (see accounting code synchronization result values attributes).

Available accounting category attributes in data param:

Name	Type	Required?	Can be blank?	Description
accounting_type	String	True	False	Name of an accounting type that already exists for your organisation in MyServe
name	String	True	False	accounting category name
description	String	False	True	Free-text description; six are available
description_2	String	False	True	Free-text description; six are available
description_3	String	False	True	Free-text description; six are available
description_4	String	False	True	Free-text description; six are available
description_5	String	False	True	Free-text description; six are available
description_6	String	False	True	Free-text description; six are available
tax_jurisdiction	String	False	True	Tax jurisdiction of the category
additional_status	String	False	True	Your own status for the category
approval_managers	Array	False	True	If an accounting type requires approval managers, this attribute is required. See below.

Attributes for an Approval manager of Accounting

Each approval manager is identified by employee_number, name or email; the person must already exist in MyServe.

Name	Type	Required?	Description
employee_number	String	False	Employee Number
name	String	False	Name
email	String	False	Email

Query Response

Type: JSON

HTTP status code: 200 on success and when some rows fail (see results), and 200 with a message when the request is refused; 429 while a previous synchronization for your organisation still holds the lock.

Name	Type	Presence	Description
message	String	always	"Successfully performed", "Errors occurred during the perform" (see results) or "Job successfully created" (asynchronous or still running)
job_id	Integer	unless refused	ID of a created job (use it to get job status)
results	Hash	sync request only	Key - accounting category name or 'Common' which means that this info doesn't connected with some accounting category, value - hash with status, accounting type ID and name and maybe array of errors (see accounting code synchronization result values attributes).

Accounting code synchronization result values attributes

Name	Type	Description
status	String	Accounting category sync status. Possible values: created / updated / error
accounting_type	String	Accounting type name
accounting_type_id	Integer	Accounting Type ID
errors	Array	Errors array (when occured)

Fail Response

Name	Type	Description
message	String	Why the request was refused: "Invalid API token provided", "Not allowed IP", "sandbox attribute should have a Boolean value" or "Too many requests" (HTTP 429)

Check synchronization status of accounting categories

Example:

curl -d "{\"job_id\": \"154\"}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/accounting_categories/synchronization_status

Success Response (performing)

{
  "status": "performing",
  "results": {}
}

Success Response (completed)

{
  "status": "completed",
  "results": {
    "accounting category 1": {
      "status": "created",
      "accounting_type": "accounting type 1",
      "accounting_type_id": 1
    }
  }
}

Fail Response

{
  "status": "errored",
  "results": {
    "accounting category 1": {
      "status": "error",
      "errors": [ "Approval manager 'Mike Tyson' does not exist for attaching" ]
    }
  }
}

{
  "message": "Job not found"
}

HTTP Request

POST: /api/v1/clients/accounting_categories/synchronization_status

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
job_id	Body	Integer	True	Job ID

Query Response

Type: JSON

HTTP status code: 200, including when the job is not found; 403 when the job belongs to another organisation.

Name	Type	Description
status	String	Status of synchronization
results	Hash	Hash with results of synchronization; empty until the job has run

Fail Response

Name	Type	Description
message	String	"Job not found" (HTTP 200) or "Access forbidden" (HTTP 403, the job belongs to another organisation)

Hardware Ordering API

Hardware ordering lets you order devices and accessories from your carriers' dealers through MyServe. Read the products and accessories you are allowed to order, look up the city (Canada) or ZIP code (United States) for the line, create the order, then read it to follow its state.

Get list of customer hardware orders

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX "https://myserve.co/api/v1/clients/orders?page=1"

Success Response

{
  "total_count": 1,
  "page": "1",
  "total_pages": 1,
  "data": [
    {
      "uuid": "338abf3f-c87b-4434-af4b-7e578db2c8a6",
      "state": "Completed",
      "carrier_name": "CarrierName",
      "dealer": {
        "name": "DealerName",
        "address": "Earth",
        "city": "CityName",
        "phone": "123456"
      },
      "requester_emails": ["john@example.com"],
      "shipping_info": {
        "address": "Earth",
        "address1": "Avenue",
        "address2": "Avenue 2",
        "province": "SK",
        "attention": "Note",
        "postal_code": "12345",
        "city": "City",
        "country": "Country"
      },
      "dealer_message": "dealer message",
      "pdf_invoice_recipient": "pdf_1@example.com",
      "meta": {"request_number": "123456"},
      "purchase_order_number": "942400 ORDER# 40011",
      "order_items": [
        {
          "state": "Approval",
          "product_id": 14213,
          "color": null,
          "number": null,
          "imei": "1234567890",
          "sim": "1234567890",
          "sim_type": null,
          "eid": null,
          "imei2": null,
          "reason": "other",
          "custom_reason": "stolen",
          "billing_account_number": "12345678",
          "employee": {
            "name": "Chuck N",
            "email": "a@example.com",
            "phone": "123456",
            "address": "Earth",
            "employee_number": "12345",
            "job_title": "PR Manager"
          },
          "device_term": {
            "name": "No Term (64GB)",
            "price": 500.0
          },
          "accessories": [
            {
              "id": 789,
              "name": "Jabra - Headset Jabra Motion BT In ear w/ kit (84318)",
              "quantity": 1,
              "estimated_cost": 200.0
            }
          ],
          "accounting_codes": [
            {
              "type_name": "GL Account",
              "category_name": "1234356"
            },
            {
              "type_name": "Sub Account",
              "category_name": "4567"
            }
          ],
          "city": null,
          "meta": {"request_number": "123456"},
          "port_request": {}
        }
      ],
      "tax": "Sask PST (6%)"
    }
  ]
}

Success Response

Name	Type	Description
total_count	Integer	Total orders count
page	Integer	Current page (only with parameter page)
total_pages	Integer	Total page numbers (only with parameter page)
data	Array	Array of orders (field descriptions below)

Fail Response

{
  "message": "Invalid API token provided"
}

HTTP Request

GET: /api/v1/clients/orders

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
page	URL	Integer	False	Page number, 100 orders per page. Without it, all orders are returned.

Query Response

Type: JSON

HTTP status code: 200 on success, and also 200 with a message when the request is refused (invalid API token or caller address not allowed).

Fail Response

Name	Type	Description
message	String	Why the request was refused, for example "Invalid API token provided" or "Not allowed IP"

Get hardware order information

Example:

curl -H "API_TOKEN:XXXXXXXXXXXXXX" https://myserve.co/api/v1/clients/orders/9217aa72-6df5-47fe-884c-943ce213ecda

Success Response

{
  "status": "succeeded",
  "data": {
    "uuid": "338abf3f-c87b-4434-af4b-7e578db2c8a6",
    "state": "Completed",
    "carrier_name": "CarrierName",
    "dealer": {
      "name": "DealerName",
      "address": "Earth",
      "city": "CityName",
      "phone": "123456"
    },
    "requester_emails": ["john@example.com"],
    "shipping_info": {
      "address": "Earth",
      "address1": "Avenue",
      "address2": "Avenue 2",
      "province": "SK",
      "attention": "Note",
      "postal_code": "12345",
      "city": "City",
      "country": "Country"
    },
    "dealer_message": "dealer message",
    "pdf_invoice_recipient": "pdf_1@example.com",
    "meta": {"request_number": "123456"},
    "purchase_order_number": "942400 ORDER# 40011",
    "order_items": [
      {
        "state": "Approval",
        "product_id": 14213,
        "color": null,
        "number": null,
        "imei": "1234567890",
        "sim": "1234567890",
        "reason": "other",
        "custom_reason": "stolen",
        "billing_account_number": "12345678",
        "employee": {
          "name": "Chuck N",
          "email": "a@example.com",
          "phone": "123456",
          "address": "Earth",
          "employee_number": "12345",
          "job_title": "PR Manager"
        },
        "device_term": {
          "name": "No Term (64GB)",
          "price": 500.0
        },
        "accessories": [
          {
            "id": 789,
            "name": "Jabra - Headset Jabra Motion BT In ear w/ kit (84318)",
            "quantity": 1,
            "estimated_cost": 200.0
          },
          ...
        ],
        "accounting_codes": [
          {
            "type_name": "GL Account",
            "category_name": "1234356"
          },
          {
            "type_name": "Sub Account",
            "category_name": "4567"
          }
        ],
        "city": null,
        "meta": {"request_number": "123456"},
        "port_request": {
          "authorized_first_name": "FirstName",
          "authorized_last_name": "LastName",
          "transfer_date": "yyyy-mm-dd",
          "prev_carrier_account": "12345678",
          "prev_carrier_name": "CarrierName"
        }
      }
    ],
    "tax": "Sask PST (6%)"
  }
}

Fail Response

{ "status": "failed", "error": "Order not found" }

HTTP Request

GET: /api/v1/clients/orders/<order-uuid>

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
bell_info	URL	Boolean	False	Show Bell OrdersInfo. (Default: false)

Query Response

Type: JSON

HTTP status code: 200 on success; 404 when no order of yours has this uuid; 200 with a message when the request is refused.

Name	Type	Description
status	String	Status (succeeded / failed)
error	String	"Order not found" when the order does not exist (HTTP 404)
data	Hash	Order data. See order attributes.

Attributes for an order

Name	Type	Description
uuid	String	Order ID
state	String	Order State (Possible values: Configuration, Waiting for approval, Select dealer, Purchase order, Contact to the Dealer, Confirmed, Cancelled, Postponed, Completed)
carrier_name	String	Carrier Name
dealer	Hash	Dealer data. See Dealer attributes.
requester_emails	Array	An array of emails that will be notified when order status changed
shipping_info	Hash	Shipping data information. See Shipping information attributes.
dealer_message	String	Dealer message
pdf_invoice_recipient	String	Comma separated list of emails or one email to receive a PDF version of invoice
order_items	Array	Order Items information. See Order Item attributes.
tax	String	Taxes Information
meta	Hash	Additional order information
purchase_order_number	String	Purchase Order Number
bell_info	Hash	Bell Orders Info. Included only if bell_info query parameter is true. See Bell info attributes.

Attributes for a dealer

Name	Type	Description
name	String	Name
address	String	Address
city	String	City
phone	String	Phone number

Shipping information attributes

Name	Type	Description
address	String	Address
address1	String	Shipping address1
address2	String	Shipping address2
province	String	Shipping province
attention	String	Shipping attention
postal_code	String	Shipping postal code
city	String	Shipping city
country	String	Shipping country

Attributes for an order item

Name	Type	Description
state	String	Order State (Possible values: Configuration, Waiting for approval, Select dealer, Purchase order, Contact to the Dealer, Confirmed, Cancelled, Postponed, Completed)
product_id	Integer	Product ID
color	String	Product Color
number	String	Number of the replacing device or port-in number if port request fields are present
imei	String	New Product IMEI
sim	String	New Product SIM
sim_type	String	SIM type
eid	String	eSIM identifier (EID)
imei2	String	Second IMEI of a dual-SIM device
reason	String	Reason for the device replacement (eligible_for_upgrade / broken / lost / other)
custom_reason	String	Reason details, for replacement items only. Required when reason is broken or lost. Optional when reason is other: if it is left out, MyServe stores Other. Never needed when reason is eligible_for_upgrade.
billing_account_number	String	Billing Account number
city	String	City of use
employee	Hash	Employee data. See employee attributes.
device_term	Hash	Device term information. See term attributes.
accessories	Array	An array of acessories info. See accessory attributes.
accounting_codes	Array	Business unit. See accounting code attributes.
meta	Hash	Additional order item information
port_request	Hash	Port-In information. See port_request attributes.

employee attributes

Name	Type	Description
email	String	Email
phone	String	Phone number
address	String	Address
job_title	String	Job title
employee_number	String	Employee number

device_term attributes

Name	Type	Description
name	String	Term name
price	Float	Term cost

accounting_code attributes

Name	Type	Description
type_name	String	Accounting Type name
category_name	String	Accounting Category name

accessory attributes

Name	Type	Description
id	Integer	Accessory ID
quantity	Integer	Number of ordered accessories
name	String	Accessory Name
estimated_cost	Float	Estimated Accessory Cost

accounting_code attributes

Name	Type	Description
type_name	String	Accounting Type name
category_name	String	Accounting Category name

port_request attributes

Name	Type	Required	Description
authorized_first_name	String	False	Authorized first name
authorized_last_name	String	False	Authorized last name
transfer_date	String	False	Transfer Date (this should be yyyy-mm-dd)
prev_carrier_account	String	True	Previous Carrier Account Number
prev_carrier_name	String	False	Previous Carrier Name

Get Bell Order Info:

curl -H "API_TOKEN:XXXXXXXXXXXXXX" https://myserve.co/api/v1/clients/orders/9217aa72-6df5-47fe-884c-943ce213ecda?bell_info=true

{
  "status": "succeeded",
  "data": {
    "uuid": "338abf3f-c87b-4434-af4b-7e578db2c8a6",
    "state": "Completed",
    ...
    "bell_info": {
      "orders": [
        {
          "date_shipped": "2021-04-16",
          "date_ordered": "2021-04-10",
          "date_invoice": "2021-04-11",
          "days_open": 5,
          "po_number": "0125959",
          "shipping_address": "100, 10000-123 St Edmonton Alberta ABCDEF",
          "company_identifier": "Some Company Canada (T083)",
          "taxes": { "GST": 2.0, "HST-ON": 3.0 },
          "total": 6.0,
          "devices": [
            {
              "quantity": 1,
              "device_number": "8147699086",
              "username": "Device Username",
              "sku": "23988383858238",
              "imei": "959778937961011",
              "sim": "718097327074915",
              "name": "IPhone 7 32Gb",
              "contract_term": "3-years upgrade",
              "waybill": "82395823",
              "total": 3.0,
              "taxes": { "GST-SK": 1.0, "HST-ON": 1.5 },
              "device_id": 103084
            }
          ],
          "accessories": [
            {
              "quantity": 1,
              "device_number": "8147699086",
              "username": "Device Username",
              "sku": "235823952",
              "name": "AppleCare+ for iPhone 11 Pro, 11 Pro max, X, XS",
              "contract_term": null,
              "waybill": "82359235",
              "taxes": { "GST-SK": 1.0, "HST-ON": 1.5 },
              "total": 3.0,
              "device_id": 103084
            }
          ]
        }
      ]
    }
  }
}

Bell info order attributes

Name	Type	Description
orders	Array	Bell orders matched to this order. The key is absent when Bell has none yet.

Bell order device attributes

Name	Type	Description
date_shipped	String	Shipping date
date_ordered	String	Order date
date_invoice	String	Invoice date
days_open	Integer	Order days open
po_number	String	PO Number
shipping_address	String	Shipping address
company_identifier	String	Company Identifier
state	String	State of the order at Bell
taxes	Hash	Order Taxes
total	Float	Order total
devices	Array	Order devices. See Bell Order Device attributes
accessories	Array	Order accessories. See Bell Order Accessory attributes.

Bell order device attributes

Name	Type	Description
quantity	Integer	Items count
device_number	String	Device number
username	String	User name
sku	String	SKU
imei	String	IMEI
sim	String	SIM
name	String	Device name
waybill	String	Waybill
contract_term	String	Contract Term
delivery_po	String	Delivery purchase order number
invoice	String	Invoice number
device_id	Integer	Device ID in our system
taxes	Hash	Devices taxes
total	Float	Devices total

Bell order accessory attributes

Name	Type	Description
quantity	Integer	Items count
device_number	String	Device number
username	String	User name
sku	String	SKU
name	String	Accessory Name
waybill	String	Waybill
contract_term	String	Contract Term
delivery_po	String	Delivery purchase order number
invoice	String	Invoice number
device_id	Integer	Device ID in our system
taxes	Hash	Devices taxes
total	Float	Devices total

Create hardware order

Example:

curl --location --request POST 'https://myserve.co/api/v1/clients/orders' --header 'API_TOKEN: XXXXXXXXXXXXXXXX' --header 'Content-Type: application/json' --data-raw '{"carrier_name":"bell","dealer_name":"Demo Bell Dealer","requester_emails":["requester.email@example.com"],"shipping_province":"AB","shipping":{"company_name":"123","address1":"Address 1","address2":"Address 2","bell_api_city_id":5830,"postal_code":"2046564365","phone_number":"","attention":"","note":"note"},"shipping_attention":"John Doe","dealer_message":"Color does not matter","pdf_invoice_recipient":"pdf@example.com","order_items":[{"employee_name":"Mike Jones","product_id":3956,"bell_api_city_id":5830,"color":"","device_term":{"name":"3 year term (16GB)","price":0},"accessories":[{"id":8877,"quantity":1}],"reason":"broken","custom_reason":"how it was broken","billing_account_number":"0530762816","accounting_codes":[{"type_name":"Sub Account","category_name":"234-2245"},{"type_name":"GL Account","category_name":"44822"}]}]}'

Success Response

{
  "status": "succeeded",
  "data": {
    "uuid": "9217aa72-6df5-47fe-884c-943ce213ecda",
    "state": "Contact to the Dealer",
    "carrier_name": "Bell",
    "order_items": [
      {
        "state": "Approved",
        "product_id": 3956
      }
    ]
  }
}

Fail Response

{ "status": "failed", "errors": ["can't create order for the carrier"] }

HTTP Request

POST: /api/v1/clients/orders

Query Parameters

A * in the Required column means the rule depends on other fields; the description says when.

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
carrier_name	Body	String	True	Name of the Carrier
dealer_name	Body	String	True	Name of the Dealer
requester_emails	Body	Array	True	An array of emails that will be notified when order status changed
shipping_province	Body	String	True	An abbreviation of the shipping province. Always required and must be a valid province. If shipping.bell_api_city_id is set, the province stored with the shipping address comes from that city.
order_items	Body	Array	True	An array containing ordered items information
dealer_message	Body	String	False	Message to the dealer
pdf_invoice_recipient	Body	String	False	Comma separated list of emails or one email to receive a PDF version of invoice. Works only if 'Enable PDF Invoice Recipient' is turned on for Hardware Ordering configuration
meta	Body	Hash	False	Additional order information. Can contain any keys related to an order.
shipping_attention	Body	String	True*	Name of the person the shipment is for. Required: send it here or as shipping.attention.
shipping	Body	Hash	True	Shipping information. See shipping attributes.
purchase_order_number	Body	String	False	Purchase Order Number
purchase_order_total_cost	Body	String	False	Purchase Order Total Cost
external_reference_number	Body	String	False	ServiceNow Ticket Number

shipping attributes

Name	Type	Required	Description
company_name	String	False	Company name
address1	String	True	Address1. Must be a physical address. A P.O. box in address1, address2 or shipping_address is refused with HTTP 422 and {"status": "failed", "errors": ["Shipping address P.O. Boxes are not accepted for device shipments—please enter a physical address."]}.
address2	String	False	Address2. Must not be a P.O. box; see address1 for the refusal.
bell_api_city_id	Integer	False	Bell API city id from Cities endpoint
postal_code	String	False	Postal Code
phone_number	String	False	Telephone
attention	String	False*	Name of the person the shipment is for; used when shipping_attention is not sent. One of the two is required.
note	String	False	Note

order_items attributes for a device replacement

Name	Type	Required	Description
product_id	Integer	True	ordered product ID
color	String	False	Color
number	String	True	Number of the device being replaced. It must be one of your devices that can be upgraded, otherwise the order is refused with "Device with provided number doesn't exist or can't be upgraded". A cancelled device gets that message too; when the item's request_type is replacement, the refusal also includes "Device with provided number is cancelled and can't be upgraded".
bell_api_city_id	Integer	False*	Id of the city from the Cities endpoint. Required on every item for a Canadian carrier, including replacement and accessories items, unless the item has a port_request.
reason	String	True	Reason for the device replacement (eligible_for_upgrade / broken / lost / other)
custom_reason	String	False*	Reason details, for replacement items only. Required when reason is broken or lost. Optional when reason is other: if it is left out, MyServe stores Other. Never needed when reason is eligible_for_upgrade.
billing_account_number	String	True	Billing Account number
employee_name	String	False	Employee name
employee_number	String	False	Employee number
employee_email	String	False	Employee email
used_for	String	False	Used for
hr_locked	Boolean	False	HR locked
directory_push	Boolean	False	Directory Push
device_term	Hash	True	Device term information. See term attributes.
accessories	Array	False	An array of acessories info. See accessory attributes.
accounting_codes	Array	True	Business unit. See accounting code attributes.
request_type	String	True	Request type (new / replacement / accessory)
meta	Hash	False	Additional order information

order_items attributes for ordering a new device

Name	Type	Required	Description
product_id	Integer	True	ordered product ID
color	String	False	Color
city	String	False	City of use (NOTE: it would be nullified if port_request present)
city_based_zip_code	String	False*	City based ZIP code (*It will be validated, if given, for US customers to ensure ZIP code format compliance. It should comprise of 5-digits)
bell_api_city_id	Integer	False*	Id of the city from the Cities endpoint. Required on every item for a Canadian carrier, including replacement and accessories items, unless the item has a port_request.
number	String	True*	Previous (existing) number to port-in (*required if port_request present)
billing_account_number	String	True	Billing Account number
employee_name	String	True	Employee name
employee_number	String	False	Employee number
employee_email	String	False	Employee email
device_term	Hash	True	Device term information. See term attributes.
accessories	Array	False	An array of accessory IDs
accounting_codes	Array	True	Business unit. See accounting code attributes.
request_type	String	True	Request type (new / replacement / accessory)
meta	Hash	False	Additional order item information
port_request	Hash	False	Port-In information. See port_request attributes.

order_items attributes for ordering only accessories

Name	Type	Required	Description
bell_api_city_id	Integer	False*	Id of the city from the Cities endpoint. Required on every item for a Canadian carrier, including replacement and accessories items, unless the item has a port_request.
employee_name	String	True	Employee name
employee_number	String	False	Employee number
employee_email	String	False	Employee email
accessories	Array	True	An array of accessory IDs
accounting_codes	Array	True	Business unit. See accounting code attributes.
request_type	String	True	Request type (new / replacement / accessory)
meta	Hash	False	Additional order item information

device_term attributes

Name	Type	Required	Description
name	String	True	Term name
price	Float	True	Term cost

accessory attributes

Name	Type	Required	Description
id	Integer	True	Accessory ID
quantity	Integer	True	Number of ordered accessories

accounting_code attributes

Name	Type	Required	Description
type_name	String	True	Accounting Type name
category_name	String	True	Accounting Category name

port_request attributes

Name	Type	Required	Description
authorized_first_name	String	False	Authorized first name
authorized_last_name	String	False	Authorized last name
transfer_date	String	False	Transfer Date (this should be yyyy-mm-dd)
prev_carrier_account	String	True	Previous Carrier Account Number
prev_carrier_name	String	False	Previous Carrier Name

Query Response

Type: JSON

HTTP status code: 201 when the order is created; 422 when it is rejected; 200 with a message when the request is refused.

Name	Type	Description
status	String	Status (succeeded / failed)
errors	Array	An array of error messages
data	Hash	Order data. See order attributes.

Fail Response

A rejected order answers with HTTP status 422, status "failed" and the reasons in errors. An order for a number that is already on an open hardware order is refused with the reason "There's already an active hardware upgrade order for this device. Please complete or cancel the existing order before creating a new one.". A request that fails inside MyServe answers 422 with {"error": "The request could not be processed.", "reference": 1234, "status": "failed"} (see Errors under Getting started).

Get list of customer accessories

Example:

curl -H "API_TOKEN:XXXXXXXXXXXXXX" https://myserve.co/api/v1/clients/hardware_ordering/accessories

Success Response

{
  "data": [
    {
      "id":111,
      "name":"Bluetooth",
      "cost":"123.00",
      "category": "Category",
      "product_ids": [123],
      "device_model_ids": [1],
      "carriers": ["Bell"]
    }
  ]
}

Fail Response

{
  "message": "Invalid API token provided"
}

HTTP Request

GET: /api/v1/clients/hardware_ordering/accessories

Query Parameters

Name	Location	Type	Description
API_TOKEN	Header	String	Secret token for access to the API
product_id	URL	Integer	Optional filter accessories by product id
since	URL	Integer	Return only accessories changed since this time, in Unix time (seconds)

Query Response

Type: JSON

HTTP status code: 200 on success, and also 200 with a message when the request is refused (invalid API token or caller address not allowed).

Success Response

Name	Type	Description
data	Array	Array of accessories
data[0][id]	Integer	Accessory ID
data[0][name]	String	Accessory Name
data[0][cost]	String	Accessory cost
data[0][category]	String	Accessory category
data[0][product_ids]	Array	Array of compatible product ids
data[0][device_model_ids]	Array	Array of compatible device model ids
data[0][carriers]	Array	Array of accessory carrier names

Fail Response

Name	Type	Description
message	String	Result description of the response

Get list of customer products

Example:

curl -H "API_TOKEN:XXXXXXXXXXXXXX" "https://myserve.co/api/v1/clients/hardware_ordering/products?carrier=Bell"

Success Response

{
  "data": [
    {
      "id":111,
      "name":"iPhone",
      "device_terms": [
        {
          "name": "No Term",
          "price": 999.0,
          "description": "$999.00 - No Term"
        }
      ],
      "colors": ["white", "black"],
      "device_model_id": 1,
      "device_make": "iPhone"
    }
  ]
}

Fail Response

{
  "message": "Invalid carrier provided"
}

HTTP Request

GET: /api/v1/clients/hardware_ordering/products

Query Parameters

Name	Location	Type	Description
API_TOKEN	Header	String	Secret token for access to the API
carrier	URL	String	Name of the carrier, for example "Bell". Required; must be a carrier you can order from.

Query Response

Type: JSON

HTTP status code: 200 on success; 422 with {"message": "Invalid carrier provided"} when the carrier is missing or not one you can order from; 200 with a message when the request is refused.

Success Response

Name	Type	Description
data	Array	Array of products
data[0][id]	Integer	ID
data[0][name]	String	Name
data[0][device_terms][0][name]	String	Term name
data[0][device_terms][0][price]	Float	Term price
data[0][device_terms][0][description]	String	Term description
data[0][colors]	Array	Available colors
data[0][device_model_id]	Integer	Device model id
data[0][device_make]	String	Device make name

Fail Response

Name	Type	Description
message	String	Result description of the response

Get list of Canadian cities

Example:

curl -H "API_TOKEN:XXXXXXXXXXXXXX" "https://myserve.co/api/v1/clients/hardware_ordering/cities?page=2"

Success Response

{
  "total_count": 7025,
  "page": 2,
  "total_pages": 71,
  "data": [
    {
      "id":111,
      "is_local_calling_city": false,
      "name":"Toronto",
      "province_name":"Ontario"
    }
  ]
}

Fail Response

{
  "message": "Invalid API token provided"
}

HTTP Request

GET: /api/v1/clients/hardware_ordering/cities

Query Parameters

Name	Location	Type	Description
API_TOKEN	Header	String	Secret token for access to the API
page	URL	Integer	Page number for pagination. (100 items per page, Default: 1)

Query Response

Type: JSON

HTTP status code: 200 on success, and also 200 with a message when the request is refused (invalid API token or caller address not allowed).

Success Response

Name	Type	Description
total_count	Integer	Total orders count
page	Integer	Current page
total_pages	Integer	Total pages
data	Array	Array of cities
data[0][id]	Integer	ID
data[0][is_local_calling_city]	Boolean	Local Calling City?
data[0][name]	String	Name
data[0][province_name]	String	Province name

Fail Response

Name	Type	Description
message	String	Result description of the response

Get list of ZIP codes

United States ZIP codes known to MyServe, 100 per page. Use a code as an order item's city_based_zip_code.

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX "https://myserve.co/api/v1/clients/hardware_ordering/zip_codes?page=1"

Success Response

{
  "total_count": 40844,
  "page": 1,
  "total_pages": 409,
  "data": [
    {
      "id": 1,
      "city": "Holtsville",
      "code": "00501",
      "province_code": "NY",
      "province_name": "New York"
    }
  ]
}

Fail Response

{
  "message": "Invalid API token provided"
}

HTTP Request

GET: /api/v1/clients/hardware_ordering/zip_codes

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
page	URL	Integer	False	Page number, 100 ZIP codes per page, default 1

Query Response

Type: JSON

HTTP status code: 200 on success, and also 200 with a message when the request is refused (invalid API token or caller address not allowed).

Success Response

Name	Type	Description
total_count	Integer	Total number of ZIP codes
page	Integer	Current page
total_pages	Integer	Total pages
data	Array	Array of ZIP codes
data[0][id]	Integer	Id of the ZIP code in MyServe
data[0][city]	String	City name
data[0][code]	String	The ZIP code
data[0][province_code]	String	State code
data[0][province_name]	String	State name

Fail Response

Name	Type	Description
message	String	Why the request was refused, for example "Invalid API token provided" or "Not allowed IP"

SIM Card Changes API

A SIM card change asks the carrier to move a line to a new physical SIM card (the API cannot request an eSIM), for example after a SIM is lost or damaged. Create the request, then read it until it is finished or canceled.

Get status of SIM card change request

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX https://myserve.co/api/v1/clients/device_requests/sim_card_changes/14422

Success Response

{ "status": "started" }

Fail Response

{
  "message": "Invalid API token provided"
}

HTTP Request

GET: /api/v1/clients/device_requests/sim_card_changes/:id

Query Parameters

Name	Location	Type	Description
API_TOKEN	Header	String	Secret token for access to the API
:id	URL	Integer	ID of SIM card change request

Query Response

Type: JSON

HTTP status code: 200 on success, and also 200 with a message when the request is refused (invalid API token or caller address not allowed); 404 when there is no request of yours with this id.

Success Response

Name	Type	Description
status	String	SIM card change request status

Fail Response

An id that is not one of your requests answers with HTTP status 404 and {"id": ["SIM card change request not found"]}.

Create new SIM card change request

Example:

curl -d "{\"number\":\"7805550123\",\"old_sim\":\"8930212345678901234\",\"new_sim\":\"8930298765432109876\"}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/device_requests/sim_card_changes

Success Response

{ "id": 14424 }

Fail Response

{ "new_identifier": ["can't be blank"] }

{ "sim_card_change": ["request already exists and not completed"] }

HTTP Request

POST: /api/v1/clients/device_requests/sim_card_changes

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
number	Body	String	True	Phone number of the device
old_sim	Body	String	False	Current SIM card number
new_sim	Body	String	True	New SIM card number
external_reference_number	Body	String	False	Your reference for this request

Query Response

Type: JSON

HTTP status code: 201 when the request is created; 422 when it is rejected; 200 with a message when the request is refused.

Name	Type	Description
id	Integer	ID of created SIM card change request

Fail Response

A rejected request answers with HTTP status 422 and the reasons, keyed by field: number when the number is not one of your devices, device when it is missing, new_identifier when new_sim is missing. A request identical to one still open (same line, same old and new SIM) is refused with {"sim_card_change": ["request already exists and not completed"]}; a request for a different new SIM on the same line is accepted. A request that fails inside MyServe answers 422 with {"error": "The request could not be processed.", "reference": 1234} (see Errors under Getting started).

Tickets API

A ticket is a support or procurement request your organisation sends to the MyServe team, for example to ask for a change no other endpoint covers. Create a ticket, then read it until its status is completed or cancelled.

Get list of tickets

Example:

curl -H "API_TOKEN:XXXXXXXXXXXXXX" "https://myserve.co/api/v1/clients/tickets?since=1760572800"

Success Response

{
  "data": [
    {
      "id": 19030,
      "subject": "Subject",
      "ticket_type": "helpdesk",
      "additional_info": { "phone_number": "4010000000" },
      "notify_emails": ["email@example.com"],
      "comment": "Comment",
      "status": "pending"
    }
  ]
}

Fail Response

{
  "message": "Invalid API token provided"
}

HTTP Request

GET: /api/v1/clients/tickets

Query Parameters

Name	Location	Type	Description
API_TOKEN	Header	String	Secret token for access to the API
since	URL	Integer	Return only tickets changed since this time, in Unix time (seconds)

Query Response

Type: JSON

HTTP status code: 200 on success, and also 200 with a message when the request is refused (invalid API token or caller address not allowed).

Success Response

Name	Type	Description
data	Array	Array of tickets. See Ticket.

ticket attributes

Name	Type	Description
subject	String	Ticket subject
ticket_type	String	Ticket type "helpdesk" or "procurement"
additional_info	Object	Any additional ticket info
notify_emails	Array	Emails to notify after complete or cancel ticket
comment	String	Message when ticket comes to "canceled" or "completed"
status	String	Current ticket status "pending", "completed" or "cancelled"

Fail Response

Name	Type	Description
message	String	Result description of the response

Get ticket data

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX https://myserve.co/api/v1/clients/tickets/19030

Success Response

{ "subject": "Subject",
  "ticket_type": "helpdesk",
  "additional_info": { "phone_number": "123" },
  "notify_emails": ["email@example.com"],
  "comment": "Comment",
  "status": "pending"
 }

Fail Response

{
  "message": "Invalid API token provided"
}

HTTP Request

GET: /api/v1/clients/tickets/:id

Query Parameters

Name	Location	Type	Description
API_TOKEN	Header	String	Secret token for access to the API
:id	URL	Integer	ID of ticket

Query Response

Type: JSON

HTTP status code: 200 on success, and also 200 with a message when the request is refused; 404 when none of your tickets has this id.

Success Response

Name	Type	Description
subject	String	Ticket subject
ticket_type	String	Ticket type "helpdesk" or "procurement". Default helpdesk
additional_info	Object	Any additional ticket info
notify_emails	Array	Emails to notify after complete or cancel ticket (optional)
comment	String	Message when ticket comes to "canceled" or "completed"
status	String	Current ticket status "pending", "completed" or "cancelled"

Fail Response

An id that is not one of your tickets answers with HTTP status 404 and {"status": "failed", "error": "Ticket not found"}.

Create new ticket

Example:

curl -d "{\"subject\":\"subject\",\"ticket_type\":\"helpdesk\",\"additional_info\":{\"attribute\":\"attribute\"}, \"notify_emails\":[\"email@example.com\"]}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/tickets

Success Response

{
  "id": 19032,
  "subject": "subject",
  "ticket_type": "helpdesk",
  "additional_info": { "attribute": "attribute" },
  "notify_emails": ["email@example.com"],
  "comment": null,
  "status": "pending"
}

Fail Response

{
  "errors": {
    "subject": ["can't be blank"]
  },
  "data": {
    "subject": "",
    "ticket_type": "helpdesk",
    "additional_info": { "attribute": "attribute" },
    "notify_emails": ["email@example.com"],
    "ticket": { "subject": "", "ticket_type": "helpdesk" }
  }
}

HTTP Request

POST: /api/v1/clients/tickets

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
subject	Body	String	True	Ticket subject
ticket_type	Body	String	False	Ticket type "helpdesk" or "procurement". Default helpdesk
additional_info	Body	Object	False	Any additional ticket info
notify_emails	Body	Array	False	Emails to notify after complete or cancel ticket (optional)

Query Response

Type: JSON

HTTP status code: 201 when the ticket is created; 422 when it is rejected; 200 with a message when the request is refused.

Name	Type	Description
id	Integer	ID of created ticket
subject	String	Ticket subject
ticket_type	String	Ticket type "helpdesk" or "procurement"
additional_info	Object	Any additional ticket info
notify_emails	Array	Emails to notify after complete or cancel ticket (optional)
comment	String	Message when ticket comes to "canceled" or "completed"
status	String	Current ticket status "pending", "completed" or "cancelled"

Fail Response

A rejected ticket answers with HTTP status 422, the reasons in errors (keyed by field) and the parameters you sent in data. A request that fails inside MyServe answers 422 with {"error": "The request could not be processed.", "reference": 1234} (see Errors under Getting started).

Data Usage API

Billed data usage per device for the current billing period of one business account, from the data MyServe has received for that account.

Get devices current month data usage by business account

Example:

curl -H "API_TOKEN:XXXXXXXXXXXXXX" "https://myserve.co/api/v1/clients/data_usage/by_business_account?business_account=123456"

Success Response

{
  "data": [
    {
      "number": "7805550123",
      "total_volume": 1024,
      "username": "Chuck N"
    }
  ]
}

Fail Response

{
  "message": "Business account not found"
}

HTTP Request

GET: /api/v1/clients/data_usage/by_business_account

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
business_account	URL	String	True	Business account number (from the account_number of your devices)

Query Response

Type: JSON

HTTP status code: 200 on success; 404 when the business account is not one of yours; 200 with a message when the request is refused (invalid API token or caller address not allowed).

Success Response

Name	Type	Description
data	Array	Array of data usage
data[0][number]	String	Device number
data[0][username]	String	Username
data[0][total_volume]	Integer	Current month total data usage

Fail Response

Name	Type	Description
message	String	Why the request was refused or failed, for example "Business account not found" or "Invalid API token provided"

An unknown business account answers with HTTP status 404 and {"message": "Business account not found"}.

In Month Data Usage API

In-month data usage is the usage the carrier has reported so far in the current billing cycle, before the bill arrives. Read it per device, or per pooled business account.

Get device In Month data usage

Example:

curl -H "API_TOKEN:XXXXXXXXXXXXXX" "https://myserve.co/api/v1/clients/in_month_data_usage/by_number?number=7805550123"

Success Response

{
  "data": [
    {
      "date": "2026-10-09",
      "data": 1048576
    }
  ]
}

Fail Response

{
  "status": "failed",
  "error": "Device not found"
}

HTTP Request

GET: /api/v1/clients/in_month_data_usage/by_number

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
number	URL	String	True	Device number

Query Response

Type: JSON

HTTP status code: 200 on success; 404 with {"status": "failed", "error": "Device not found"} when the number is not one of your devices; 200 with a message when the request is refused.

Success Response

Name	Type	Description
data	Array	Array of daily usage
data[0][date]	String	Usage date
data[0][data]	Integer	Used data in bytes

Fail Response

Name	Type	Description
message	String	Why the request was refused or failed

Get business accounts In Month data usage

Example:

curl -H "API_TOKEN:XXXXXXXXXXXXXX" https://myserve.co/api/v1/clients/in_month_data_usage/business_accounts

Success Response

{
  "data": [
    {
      "account_number":"123456",
      "billing_account_data_pool_id": 7624,
      "log_date": "2026-10-16",
      "pool_size": 512,
      "pool_usage": 1024
    }
  ]
}

Fail Response

{
  "message": "Invalid API token provided"
}

HTTP Request

GET: /api/v1/clients/in_month_data_usage/business_accounts

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API

Query Response

Type: JSON

HTTP status code: 200 on success, and also 200 with a message when the request is refused. Only pooled business accounts that are not hidden or ignored are included, from the start of their current billing cycle.

Success Response

Name	Type	Description
data	Array	Array of daily usage
data[0][account_number]	String	Business account number
data[0][billing_account_data_pool_id]	Integer	Id of the data pool
data[0][log_date]	String	Date of the reading
data[0][pool_size]	Float	Size of the pool
data[0][pool_usage]	Float	Usage of the pool on that date

Fail Response

Name	Type	Description
message	String	Why the request was refused or failed

Wirelines API

A wireline is a fixed (landline) service, such as a business line, fax line or toll-free number, billed on a wireline account. Use these endpoints to read your wirelines and to keep MyServe in step with your own inventory.

Get list of customer wirelines

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX https://myserve.co/api/v1/clients/wirelines

Success Response

{
  "data": [
    {
      "username": "Name",
      "status": "active",
      "number": "1234567890",
      "model": "Model",
      "email": "test@email.com",
      "employee_number": "0123456789",
      "contract_expiry_date": "2020-01-01",
      "description": "test",
      "location": "Location",
      "used_for": "Final Bill",
      "service_address": "Address",
      "subtype": "ADSL",
      "warehouse": "warehouse",
      "wireline_account": "123456789"
    }, {...}
  ]
}

Fail Response

{
  "message": "Invalid API token provided"
}

HTTP Request

GET: /api/v1/clients/wirelines

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API

Query Response

Type: JSON

HTTP status code: 200 on success, and also 200 with a message when the request is refused (invalid API token or caller address not allowed).

Success Response

Name	Type	Description
data	Array	Array of wirelines
data[0][username]	String	Username
data[0][status]	String	Wireline status
data[0][number]	String	Number
data[0][model]	String	Wireline model
data[0][email]	String	Email address
data[0][employee_number]	String	Employee number
data[0][contract_expiry_date]	String	Contract expiration date
data[0][description]	String	Description of the line
data[0][location]	String	Location of the line
data[0][used_for]	String	What the line is used for
data[0][service_address]	String	Address where the service is installed
data[0][subtype]	String	Kind of line, for example "Fax" or "Toll Free"
data[0][warehouse]	String	Warehouse
data[0][wireline_account]	String	Name of the wireline account the line is billed on

Fail Response

Name	Type	Description
message	String	Why the request was refused, for example "Invalid API token provided" or "Not allowed IP"

Synchronize lists of wirelines

Example:

curl -d "{\"data\": [{\"number\":\"7809000000\", \"username\":\"username\",\"status\":\"active\",\"model\":\"Model\",\"email\":\"a@example.com\", \"employee_number\":\"12345\", \"location\":\"Earth\", \"contract_expiry_date\":\"2027-01-01\", \"description\":\"text\", \"subtype\":\"Fax\", \"wireline_account\":\"Head office lines\" }]}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/wirelines/synchronize

Success Response (sync)

{
  "message": "Successfully performed",
  "job_id": 158,
  "results": {
    "7809000000": {
      "status": "created"
    },
    "7809000001": {
      "status": "updated"
    }
  }
}

Fail Response (sync)

{
  "message": "Errors occurred during the perform",
  "job_id": 159,
  "results": {
    "7809000000": {
      "status": "error",
      "errors": [
        "This wireline account doesn't exist on this customer"
      ]
    },
    "7809000001": {
      "status": "updated"
    }
  }
}

Success Response (async)

{
  "message": "Job successfully created",
  "job_id": 160
}

Fail Response

{
  "message": "Too many requests"
}

HTTP Request

POST: /api/v1/clients/wirelines/synchronize

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
data	Body	Array	True	Array of wirelines data
sandbox	Body	Boolean	False	Turn on/off sandbox mode. If sandbox mode turned on, then changes will not apply to the customer account.
async	Body	Boolean	False	Turn on/off async mode. If it is turned on, then perform synchronization asynchronously. Default: false. Requests with more than 300 rows always run asynchronously.

Available wireline attributes in data param

Name	Type	Required?	Can be blank?	Description
number	String	True	False	Phone number of the line; used to find the line
username	String	False	False	username
status	String	False	False	Line status, for example "active"; required for a new line
model	String	False	False	Model
email	String	False	True	Email address
employee_number	String	False	True	Employee number
contract_expiry_date	String	False	True	date in format yyyy-mm-dd
description	String	False	False	Description of the line
location	String	False	True	Location of the line
used_for	String	False	False	What the line is used for
service_address	String	False	False	Address where the service is installed
subtype	String	False	True	Kind of line: ADSL, Centrex Line, Direct In Dial (DID), Extension, Fax, IBL (Business Line), ISDN, Local Business Line, PRI or Toll Free
warehouse	String	False	False	Warehouse
wireline_account	String	TRUE for new wirelines	False	Name of a wireline account that already exists for your organisation in MyServe

Query Response

Type: JSON

HTTP status code: 200 on success and when some rows fail (see results), and 200 with a message when the request is refused; 429 while a previous synchronization for your organisation still holds the lock.

Response

Name	Type	Presence	Description
message	String	always	"Successfully performed", "Errors occurred during the perform" (see results) or "Job successfully created" (asynchronous or still running)
job_id	Integer	unless refused	ID of a created job (use it to get job status)
results	Hash	sync request only	Key - wireline number or 'Common' which means that this info doesn't connected with some wireline, value - hash with some info like status and maybe array of errors

Fail Response

Name	Type	Description
message	String	Why the request was refused: "Invalid API token provided", "Not allowed IP", "sandbox attribute should have a Boolean value" or "Too many requests" (HTTP 429)

Check wirelines synchronization job status

Example:

curl -d "{\"job_id\": \"158\"}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/wirelines/synchronization_status

Success Response (performing)

{
  "status": "performing",
  "results":  {}
}

Success Response (completed)

{
  "status": "completed",
  "results": {
    "7809000000": {
      "status": "created"
    }
  }
}

Fail Response

{
  "status": "errored",
  "results": {
    "7809000000": {
      "errors": [
        "This wireline account doesn't exist on this customer"
      ],
      "status": "error"
    }
  }
}

{
  "message": "Job not found"
}

HTTP Request

POST: /api/v1/clients/wirelines/synchronization_status

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
job_id	Body	Integer	True	Job ID

Query Response

Type: JSON

HTTP status code: 200, including when the job is not found; 403 when the job belongs to another organisation.

Name	Type	Description
status	String	Status of synchronization
results	Hash	Hash with results of synchronization; empty until the job has run

Fail Response

Name	Type	Description
message	String	"Job not found" (HTTP 200) or "Access forbidden" (HTTP 403, the job belongs to another organisation)

Billing Data Lines API

A billing data line is one device's charges and usage on one carrier bill that MyServe has processed, 100 lines per page. Filter by cycle date, device number or business account to reconcile costs.s

Get list of device billing data lines

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX "https://myserve.co/api/v1/clients/billing_data_lines?page=1&cycle_date=2026-10-01&business_account=1234"

Success Response

{
  "data": [
    {
      "number" : "1234567890",
      "cycle_date" : "2000-05-01",
      "status": "active",
      "device_make": "iPhone",
      "billing_account": "1234",
      "username": "username",
      "plan_name_and_costs": [
        { "name": "plan name", "charge": 100 }
       ],
      "feature_name_and_costs": {
        "Feature name": 100
       },
      "local_airtime_charges": 10.0,
      "outgoing_daytime_count": 10.0,
      "incoming_daytime_count": 10.0,
      "evenings_and_weekend_count": 10.0,
      "mobile_to_mobile_count": 10.0,
      "call_forward_count": 10.0,
      "call_forward_cost":  10.0,
      "domestic_long_distance": 10.0,
      "domestic_long_distance_cost":  10.0,
      "usa_long_distance":  10.0,
      "usa_long_distance_cost": 10.0,
      "international_long_distance":  10.0,
      "international_long_distance_cost": 10.0,
      "count_411":  10,
      "cost_411": 10.0,
      "roaming_data_usa_count": 10.0,
      "roaming_usa_cost": 10.0,
      "roaming_data_int_count": 10.0,
      "roaming_int_cost": 10.0,
      "roaming_text_count": 10.0,
      "roaming_text_cost": 10.0,
      "roaming_data_count": 10.0,
      "roaming_data_cost": 10.0,
      "roaming_voice_count": 10.0,
      "roaming_voice_cost": 10.0,
      "picture_video_msgs_count": 10,
      "picture_video_msgs_cost":  10.0,
      "local_to_usa_text_msgs_count": 10,
      "local_to_usa_text_msgs_cost":  10.0,
      "local_to_intl_text_msgs_count":  10,
      "local_to_intl_text_msgs_cost": 10.0,
      "roaming_text_msgs_count":  10,
      "roaming_text_msgs_cost": 10.0,
      "daily_roam_usa_count": 10,
      "daily_roam_usa_cost":  10.0,
      "daily_roam_intl_count":  10,
      "daily_roam_intl_cost": 10.0,
      "premium_msgs_count": 10,
      "premium_msgs_cost":  10.0,
      "subscriptions_count":  10,
      "subscriptions_cost": 10.0,
      "data_usage_domestic":  10.0,
      "data_cost_domestic": 10.0,
      "shared_inlcuded_data": 10.0,
      "shared_used_data": 10.0,
      "credits":  { "credit": 10 },
      "equipment_charges": { "Equipment Charges": 53873 },
      "equipment_cost": 10.0,
      "cancellation_costs": 10.0,
      "taxes":  10.0,
      "total_charges":  10.0,
      "text_count":  10,
      "managers": ["First Manager", "Second Manager"],
      "business_unit": [
        {
          "categories" : {
            "Account" : "123456",
            "Sub Account" : "012345"
          }
        }
      ]
    }, {...}
  ]
}

Success Response

Name	Type	Description
data	Array	Array of billing data lines
number	String	Device number
cycle_date	String	Cycle date (format: YYYY-MM-DD)
status	String	Device status
device_make	String	Device make
billing_account	String	Billing account number
username	String	Username
plan_name_and_costs	Array	Plan Name & Costs
feature_name_and_costs	Object	Feature Name & Costs
local_airtime_charges	Float	Local Airtime Charges
outgoing_daytime_count	Float	Outgoing Daytime Count
incoming_daytime_count	Float	Incoming Daytime Count
evenings_and_weekend_count	Float	Evenings & Weekend Count
mobile_to_mobile_count	Float	Mobile to Mobile Count
call_forward_count	Float	Call Forward Count
call_forward_cost	Float	Call Forward Cost
domestic_long_distance	Float	Domestic Long Distance
domestic_long_distance_cost	Float	Domestic Long Distance Cost
usa_long_distance	Float	USA Long Distance
usa_long_distance_cost	Float	USA Long Distance Cost
international_long_distance	Float	International Long Distance
international_long_distance_cost	Float	International Long Distance Cost
count_411	Float	411 Count
cost_411	Float	411 Cost
roaming_data_usa_count	Float	Roaming Data - USA Count
roaming_usa_cost	Float	Roaming - USA Cost
roaming_data_int_count	Float	Roaming Data - Int Count
roaming_int_cost	Float	Roaming - Int Cost
roaming_text_count	Float	Roaming Text - Count
roaming_text_cost	Float	Roaming - Text Cost
roaming_data_count	Float	Roaming Data - Count
roaming_data_cost	Float	Roaming - Data Cost
roaming_voice_count	Float	Roaming Voice - Count
roaming_voice_cost	Float	Roaming - Voice Cost
picture_video_msgs_count	Float	Picture/Video Msgs Count
picture_video_msgs_cost	Float	Picture/Video Msgs Cost
local_to_usa_text_msgs_count	Float	Local to USA Text Msgs Count
local_to_usa_text_msgs_cost	Float	Local to USA Text Msgs Cost
local_to_intl_text_msgs_count	Float	Local to Intl Text Msgs Count
local_to_intl_text_msgs_cost	Float	Local to Intl Text Msgs Cost
roaming_text_msgs_count	Float	Roaming Text Msgs Count
roaming_text_msgs_cost	Float	Roaming Text Msgs Cost
daily_roam_usa_count	Float	Daily Roam - USA Count
daily_roam_usa_cost	Float	Daily Roam - USA Cost
daily_roam_intl_count	Float	Daily Roam - Intl Count
daily_roam_intl_cost	Float	Daily Roam - Intl Cost
premium_msgs_count	Float	Premium Msgs Count
premium_msgs_cost	Float	Premium Msgs Cost
subscriptions_count	Float	Subscriptions Count
subscriptions_cost	Float	Subscriptions Cost
data_usage_domestic	Float	Data Usage - Domestic
data_cost_domestic	Float	Data Cost - Domestic
shared_inlcuded_data	Float	Shared Inlcuded Data
shared_used_data	Float	Shared Used Data
credits	Array	Credits
equipment_charges	Array	Equipment Charges
equipment_cost	Float	Equipment Cost
cancellation_costs	Float	Cancellation Costs
taxes	Float	Taxes
total_charges	Float	Total Charges
text_count	Float	Text Count
managers	Array	Array of managers' names
business_unit	Array	Accounting Codes

Fail Response

{
  "message": "Invalid API token provided"
}

HTTP Request

GET: /api/v1/clients/billing_data_lines

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
page	URL	Integer	False	Page number for pagination (100 items per page), default 1
number	URL	String	False	Filter by device number
business_account	URL	String	False	Filter by Billing account number
cycle_date	URL	String	False	Filter by Cycle date (format: YYYY-MM-DD)

Query Response

Type: JSON

HTTP status code: 200 on success, and also 200 with a message when the request is refused (invalid API token or caller address not allowed).

Success Response

Name	Type	Description
data	Array	Array of billing data lines

Fail Response

Name	Type	Description
message	String	Result description of the response

Accounting Reports API

The accounting report turns one processed carrier bill into cost allocation entries ready for your finance system, split by your accounting categories.

Get the accounting report for a bill

Example:

curl -d "{\"account\":\"121212\",\"date\":\"2026-10-01\"}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/reports/accounting

Success Response

{
  "data": [
    {
      "CompanyCode": "1000",
      "PostingDate": "2026-10-01",
      "HeaderText": "Bell 121212 Oct 2026",
      "AllocationLine": [
        {
          "Amount": 45.5,
          "CostCenter": "10045",
          "Currency": "CAD",
          "ItemText": "Bell 121212 Oct 2026 7805550123",
          "ExpenseType": "CELPH",
          "Tax": [
            { "TaxType": "GST", "TaxAmount": 2.28 }
          ]
        }
      ]
    }
  ]
}

Fail Response

{
  "message": "data not found"
}

{
  "message": "report not implemented for current customer"
}

HTTP Request

POST: /api/v1/clients/reports/accounting

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
account	Body	String	True	Business account number of the bill (the billing account)
date	Body	String	True	Cycle date of the bill, format YYYY-MM-DD

Query Response

Type: JSON

HTTP status code: 200 in every case: with data on success, and with a message when no bill matches, the report is not set up for your organisation, or the request is refused (invalid API token or caller address not allowed).

Success Response

Name	Type	Description
data	Array	Array of accounting entries, one per header
data[0][CompanyCode]	String	Company code
data[0][PostingDate]	String	Posting date
data[0][HeaderText]	String	Text of the entry header
data[0][AllocationLine]	Array	Allocation lines of the entry
AllocationLine[0][Amount]	Float	Amount to allocate
AllocationLine[0][CostCenter]	String	Cost center
AllocationLine[0][NetworkNumber]	String	Network number
AllocationLine[0][Activity]	String	Activity
AllocationLine[0][OrderNumber]	String	Order number
AllocationLine[0][Currency]	String	Currency, "CAD"
AllocationLine[0][ItemText]	String	Line text: the header text followed by the device number
AllocationLine[0][ExpenseType]	String	Expense type
AllocationLine[0][Tax]	Array	Taxes of the line, each with TaxType and TaxAmount

Fail Response

Name	Type	Description
message	String	"data not found" when no bill matches the account and date; "report not implemented for current customer" when the report is not set up; or why the request was refused

Transfer of Responsibility API

A transfer of responsibility moves a line between your organisation and a person or another business. Transfer in (to business) brings a line onto one of your business accounts; transfer out (from business) hands one of your lines to a person or another business. Create the request, then read it to follow its status.

There are two types of requests depending on a direction of a transfer:

• Transfer In Business requests.
• Transfer Out of Business requests.

Transfer Of Responsibility API has 4 endpoints:

• Create Transfer In Request
• Get Transfer In Request information
• Create Transfer Out Request
• Get Transfer Out Request information

Create Transfer In Request

HTTP Request

POST: /api/v1/clients/device_requests/transfer_of_responsibility/to_business

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	True	Secret token for access to the API
phone_number	Body	String	True	Phone number
employee_name	Body	String	True	Employee name
employee_number	Body	String	False	Employee number
requestor_name	Body	String	False	Name of the person asking for the transfer
rate_plan_name	Body	String	False*	Carrier rate plan name. Send this or device_make; one of the two is required. When left out, your default rate plan for the device make is used. If the device make exists but you have no default rate plan for it, the request is refused with HTTP 422 and {"errors": {"device_make": ["Cannot resolve default rate plan for device make 'Apple'"], "rate_plan_name": ["can't be blank"]}, "data": {...}, "status": "failed"}. If MyServe does not know the device make, the request is refused with HTTP 422 and {"errors": {"device_make": ["Device make 'Aple' does not exist"], "rate_plan_name": ["can't be blank"]}, "data": {...}, "status": "failed"}.
device_make	Body	String	False*	Device make. Required for a business-to-business request. For a person-to-business request, send this or rate_plan_name; one of the two is required. Also used to find your default rate plan when rate_plan_name is not passed.
business_account_number	Body	String	True	Business account number
send_to_carrier	Body	Boolean	True	Send confirm email to carrier
request_type	Body	String	False	Should be 'person-to-business' for 'Person to Business' transfers, or 'business-to-business' for 'Business to Business' transfers. Defaults to 'person-to-business' for compatibility.
sandbox	Body	Boolean	False	Turn on/off sandbox mode. If sandbox mode turned on, then changes will not apply to the customer account.
admin_name	Body	String	False	Administrator name
meta	Body	Hash	False	Additional request information
external_reference_number	Body	String	False	External Reference Number

Query Response

Type: JSON

HTTP status code: 201 when the request is created; 422 when it is rejected; 200 with a message when the request is refused.

Name	Type	Description
phone_number	String	Phone number
employee_name	String	Employee name
employee_number	String	Employee number
rate_plan_name	String	Carrier rate plan
business_account_number	String	Business account number
send_to_carrier	Boolean	Send confirm email to carrier
uuid	String	UUID of transfer of responsibility request
status	String	Request status
request_type	String	Request type
meta	Hash	Additional request information

Example of a Person to Business request:

curl -d "{\"phone_number\":\"7809000000\",\"employee_name\":\"Chuck N\",\"employee_number\":\"12345\",\"rate_plan_name\":\"Rate Plan\",\"business_account_number\":\"123456\",\"send_to_carrier\":\"true\",\"request_type\":\"person-to-business\",\"meta\":{\"internal_id\":\"1234\"}}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/device_requests/transfer_of_responsibility/to_business

Success Response

{
  "status": "succeeded",
  "data": {
    "phone_number": "7809000000",
    "employee_name": "Chuck N",
    "employee_number": "12345",
    "rate_plan_name": "Rate Plan",
    "business_account_number": "123456",
    "send_to_carrier": true,
    "status": "pending",
    "request_type": "person-to-business",
    "meta": {"internal_id": "1234"},
    "uuid": "8b456fd4-d5fd-4346-ab70-fd93cb57cbf9"
  }
}

Fail Response

{
  "status": "failed",
  "errors": {
    "phone_number": ["can't be blank"]
  },
  "data": {
    "phone_number": "7809000000",
    "employee_name": "Chuck N",
    "employee_number": "12345",
    "rate_plan_name": "Rate Plan",
    "business_account_number": "123456",
    "send_to_carrier": true,
    "status": "pending",
    "request_type": "person-to-business",
    "meta": {"internal_id": "1234"}
  }
}

Example of a Business to Business request:

curl -d "{\"phone_number\":\"7809000000\",\"employee_name\":\"Chuck N\",\"employee_number\":\"12345\",\"device_make\":\"iPhone\",\"business_account_number\":\"123456\",\"send_to_carrier\":\"true\",\"request_type\":\"business-to-business\",\"meta\":{\"internal_id\":\"1234\"}}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/device_requests/transfer_of_responsibility/to_business

Success Response

{
  "status": "succeeded",
  "data": {
    "phone_number": "7809000000",
    "employee_name": "Chuck N",
    "employee_number": "12345",
    "rate_plan_name": "Rate Plan",
    "business_account_number": "123456",
    "send_to_carrier": true,
    "status": "pending",
    "request_type": "business-to-business",
    "meta": {"internal_id": "1234"},
    "uuid": "8b456fd4-d5fd-4346-ab70-fd93cb57cbf9"
  }
}

Fail Response

{
  "status": "failed",
  "errors": {
    "phone_number": ["can't be blank"]
  },
  "data": {
    "phone_number": "7809000000",
    "employee_name": "Chuck N",
    "employee_number": "12345",
    "rate_plan_name": "Rate Plan",
    "business_account_number": "123456",
    "send_to_carrier": true,
    "status": "pending",
    "request_type": "business-to-business",
    "meta": {"internal_id": "1234"}
  }
}

Get Transfer In Request

HTTP Request

GET: /api/v1/clients/device_requests/transfer_of_responsibility/to_business/:uuid

Query Parameters

Name	Location	Type	Description
API_TOKEN	Header	String	Secret token for access to the API
:uuid	URL	String	UUID of transfer of responsibility request

Query Response

Type: JSON

HTTP status code: 200 on success; 404 when no request of yours has this uuid; 200 with a message when the request is refused.

Success Response

Name	Type	Description
phone_number	String	Phone number
employee_name	String	Employee name
employee_number	String	Employee number
rate_plan_name	String	Carrier rate plan
business_account_number	String	Business account number
send_to_carrier	Boolean	Send confirm email to carrier
uuid	String	UUID of transfer of responsibility request
status	String	Request status
request_type	String	Type of transfer. Can be 'person-to-business', or 'business-to-business'.
meta	Hash	Additional request information. Can contain any keys related to a request.

Fail Response

A uuid that is not one of your requests answers with HTTP status 404 and {"id": ["Transfer of responsibility request not found"]}.

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX https://myserve.co/api/v1/clients/device_requests/transfer_of_responsibility/to_business/8b456fd4-d5fd-4346-ab70-fd93cb57cbf9

Response

{
  "phone_number": "7809000000",
  "employee_name": "Chuck N",
  "employee_number": "12345",
  "rate_plan_name": "Rate Plan",
  "business_account_number": "123456",
  "send_to_carrier": true,
  "uuid": "8b456fd4-d5fd-4346-ab70-fd93cb57cbf9",
  "status": "pending",
  "request_type": "person-to-business",
  "meta": {"internal_id": "1234"}
}

Create Transfer Out Request

HTTP Request

POST: /api/v1/clients/device_requests/transfer_of_responsibility/from_business

Depending on a request type (see request_type parameter) there are two sets of query parameters and corresponding responses: 'Out to Person' and 'Out to Business'.

'Out to Person' Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	YES	Secret token for access to the API
request_type	Body	String	YES	Must be 'business-to-person'
phone_number	Body	String	YES	Device phone number
carrier_action	Body	String	YES	Carrier action based on the table below
confirm_legal_name	Body	String	YES	Confirm legal name
date	Body	Date	YES	Transfer date
days_before_suspend	Body	Integer	YES	Days number since request creation after that it will expire
status	Body	String	NO	Initial status of the request. Default "pending".
admin_name	Body	String	NO	Administrator name
sandbox	Body	Boolean	NO	Turn on/off sandbox mode. If sandbox mode is turned on, then changes will not apply to the customer account.
meta	Body	Hash	NO	Additional request information
external_reference_number	Body	String	False	External Reference Number

Carrier actions by action

Action	Value	Bell	Telus	Rogers	SaskTel	MTS	Verizon	AT&T
Departing Employee Process	departing_employee_process	X
Transfer Line	cancel	X	X		X	X	X	X
Allow Port-Out - Remove Port Protection	remove_port_protection	X	X	X	X	X	X	X
Number and contract Transfer	number_and_contract_transfer			X
Cancel Device with Churn (if Available)	cancel_with_churn		X

'Out to Person' Query Response

Type: JSON

HTTP status code: 201 when the request is created; 422 when it is rejected; 200 with a message when the request is refused.

Name	Type	Description
admin_name	String	Administrator name
carrier_action	String	Carrier action
confirm_legal_name	String	Confirm legal name
date	String	TTransfer date
days_before_suspend	String	Days number since request creation after that it will expire
meta	Hash	Additional request information
note	String	Approval note entered on request confirmation
phone_number	String	Device phone number
reference_number	String	Reference number entered on request confirmation (Rogers only)
request_type	String	Request type
status	String	Request status
uuid	String	UUID of transfer of responsibility request

'Out to Business' Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	YES	Secret token for access to the API
request_type	Body	String	YES	Must be 'business-to-business'
phone_number	Body	String	YES	Device phone number
business_account_number	Body	String	NO	Business account number
new_business_name	Body	String	YES	Business name to transfer device
send_to_carrier	Body	Boolean	YES	Send confirm email to carrier
admin_name	Body	String	NO	Administrator name
sandbox	Body	Boolean	NO	Turn on/off sandbox mode. If sandbox mode is turned on, then changes will not apply to the customer account.
meta	Body	Hash	NO	Additional request information

'Out to Business' Query Response

Type: JSON

HTTP status code: 201 when the request is created; 422 when it is rejected; 200 with a message when the request is refused.

Name	Type	Description
admin_name	String	Administrator name
business_account_number	String	Business account number
meta	Hash	Additional request information
new_business_name	String	Business name to transfer device
phone_number	String	Device phone number
send_to_carrier	Boolean	Send confirm email to carrier
request_type	String	Request type
status	String	Request status
uuid	String	UUID of transfer of responsibility request

Example of a 'Out to Business' request:

curl -d "{\"phone_number\":\"7809000000\",\"new_business_name\":\"New Company\",\"admin_name\":\"John Smith\",\"business_account_number\":\"123456\",\"send_to_carrier\":\"true\",\"request_type\":\"business-to-business\",\"meta\":{\"internal_id\":\"1234\"}}" -X POST -H "API_TOKEN:XXXXXXXXXXXXXXXX" -H "Content-Type:application/json" https://myserve.co/api/v1/clients/device_requests/transfer_of_responsibility/from_business

Success Response

{
  "status": "succeeded",
  "data": {
    "phone_number": "7809000000",
    "new_business_name": "New Company",
    "admin_name": "John Smith",
    "business_account_number": "123456",
    "send_to_carrier": true,
    "status": "pending",
    "request_type": "business-to-business",
    "meta": {"internal_id": "1234"},
    "uuid": "8b456fd4-d5fd-4346-ab70-fd93cb57cbf9"
  }
}

Fail Response

{
  "status": "failed",
  "errors": {
    "new_business_name": ["can't be blank"]
  },
  "data": {
    "phone_number": "7809000000",
    "new_business_name": "",
    "admin_name": "John Smith",
    "business_account_number": "123456",
    "send_to_carrier": true,
    "status": "pending",
    "request_type": "business-to-business",
    "meta": {"internal_id": "1234"},
    "uuid": "8b456fd4-d5fd-4346-ab70-fd93cb57cbf9"
  }
}

Get Transfer Out Request

HTTP Request

GET: /api/v1/clients/device_requests/transfer_of_responsibility/from_business/:uuid

Query Parameters

Name	Location	Type	Description
API_TOKEN	Header	String	Secret token for access to the API
:uuid	URL	String	UUID of transfer of responsibility request

Query Response

Type: JSON

HTTP status code: 200 on success; 404 when no request of yours has this uuid; 200 with a message when the request is refused.

Success Response

Name	Type	Description
admin_name	String	Administrator name
business_account_number	String	Business account number
meta	Hash	Additional request information
new_business_name	String	Business name to transfer device
phone_number	String	Device phone number
send_to_carrier	Boolean	Send confirm email to carrier
request_type	String	Request type
status	String	Request status
uuid	String	UUID of transfer of responsibility request

Fail Response

A uuid that is not one of your requests answers with HTTP status 404 and {"id": ["Transfer of responsibility request not found"]}.

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX https://myserve.co/api/v1/clients/device_requests/transfer_of_responsibility/from_business/8b456fd4-d5fd-4346-ab70-fd93cb57cbf9

Response

{
  "phone_number": "7809000000",
  "new_business_name": "New Company",
  "admin_name": "John Smith",
  "business_account_number": "123456",
  "send_to_carrier": true,
  "status": "pending",
  "request_type": "business-to-business",
  "meta": {"internal_id": "1234"},
  "uuid": "8b456fd4-d5fd-4346-ab70-fd93cb57cbf9"
}

Glossary

The terms these pages use, what they mean in MyServe, and where you find their values.

Accessory

An item such as a case or charger that can be ordered with a device or on its own.

Where to find it: The accessories you can order, with the products they fit: Get list of customer accessories

Account number

The carrier's number for a business account. Parameters named account, account_number, billing_account, billing_account_number and business_account all take this number.

Where to find it: Each device's account_number: Get list of customer devices

Accounting category, accounting type and split

An accounting type is a kind of cost-allocation label your organisation uses, such as GL Account or Department. An accounting category is one value of a type, such as GL Account 44822. A device or employee carries one category per type; a device can split its cost between several categories with percentages that add up to 100 (percent in the devices synchronization).

Where to find it: Your categories and the type each belongs to: Get list of customer accounting categories

API token

The secret that identifies your organisation to the API, sent in the API_TOKEN header. There is one per organisation.

Where to find it: MyServe, your organisation's Settings, Integration settings: Authentication

Billing data line

One device's charges and usage on one carrier bill that MyServe has processed, for one billing cycle.

Where to find it: By cycle date, device number or business account: Get list of device billing data lines

Business account

A billing account your organisation holds with a carrier. Devices belong to one business account; some business accounts pool their data.

Where to find it: Each device's account_number, and the pooled accounts: Get list of customer devices, Get business accounts In Month data usage

Carrier

The mobile or wireline service provider, such as Bell, Rogers or Telus.

Where to find it: Each device's carrier. The products endpoint answers only for carriers you can order from: Get list of customer products

Contract expiry date

The date the device's carrier contract ends.

Where to find it: Each device's contract_expiry_date: Get list of customer devices

Customer (.CA and .CO)

Your organisation in MyServe. The clients part of every path means the same thing. Send requests to the host of the MyServe site your organisation signs in to.

Where to find it: The site you sign in to: Hosts and versions

In-month and billed data usage

In-month data usage is what the carrier has reported so far in the current billing cycle, before the bill arrives. Billed data usage comes from the carrier's bill once MyServe has processed it.

Where to find it: In-month per device, and billed per business account: Get device In Month data usage, Get devices current month data usage by business account

Device

A mobile line, identified by its phone number, with the handset, user, carrier, business account and accounting categories attached to it.

Where to find it: Your devices: Get list of customer devices

Device status

active, suspended or cancelled. Only these three values exist; a change of status at the carrier is asked for with a status change request.

Where to find it: Each device's status, and the change request: Change device status

Employee

A person in your organisation who can be assigned devices and can be a manager or an approval manager.

Where to find it: Your employees: Get list of customer employees

Employee number

Your own unique number for an employee. Devices and orders refer to employees by it.

Where to find it: Each employee's number: Get list of customer employees

Evergreen date

When your organisation uses device evergreen, MyServe sets this date each time a device's IMEI changes (a new handset): the change date plus your evergreen term in months, less one day. It marks when the handset is due for renewal.

Where to find it: Each device's evergreen_date: Get list of customer devices

IMEI

The 15-digit number that identifies a handset. A new IMEI on a device means a new handset.

Where to find it: Each device's imei_number: Get list of customer devices

Manager and approval manager

A manager is the employee a device or employee reports to. An approval manager is an employee who approves orders charged to an accounting category; some accounting types require one.

Where to find it: Each employee's manager_name, and each category's approval_managers: Get list of customer employees, Get list of customer accounting categories

Order and product

An order is a request to your carrier's dealer for devices or accessories. A product is a device model you may order from a carrier, with its terms and prices.

Where to find it: Your orders, and the products you can order: Get list of customer hardware orders, Get list of customer products

Sandbox

A request flag (sandbox: true) that checks a synchronization or transfer without saving anything.

Where to find it: How it behaves: The sandbox flag

SIM number

The number printed on a SIM card (also called ICCID).

Where to find it: Each device's sim_number; a SIM card change request sets a new one: Create new SIM card change request

Synchronization job

The work a synchronize request starts. Its status is created, performing, completed or errored; the last two are final. It ends errored if any row failed, even when the other rows were applied.

Where to find it: The job_id a synchronize request returns, and the status endpoints: Check devices synchronization job status

Ticket

A support or procurement request to the MyServe team. Its status is pending, completed or cancelled.

Where to find it: Your tickets: Get list of tickets

Transfer of responsibility (in and out)

Moving a line between your organisation and a person or another business. In (to business) brings a line onto one of your business accounts; out (from business) hands one of your lines over.

Where to find it: The two request types: Create Transfer In Request, Create Transfer Out Request

Wireline

A fixed (landline) service such as a business line, fax line or toll-free number, billed on a wireline account.

Where to find it: Your wirelines: Get list of customer wirelines