MyServe API Documentation

https://myserve.ca/api/:version/clients — if customer is on .CA

https://myserve.co/api/:version/clients — if customer is on .CO

Current version is V1, but this parameter is not required. If you don't specify a version, you'll automatically use the newest one.

Devices API

This API is available for customers and provide abilities to read and synchronize devices.

Get list of customer devices

Example:

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

Success Response

{
  "data": [
    {
      "username": "Name",
      "number": "1234567890",
      "customer_id": "1",
      "device_id": "1",
      "status": "active",
      "device_make_and_model": "iPhone 5",
      "device_make_name": "iPhone",
      "device_email": "test@email.com",
      "business_unit": [
        {
          "categories" : {
            "Account" : "123456",
            "Sub Account" : "012345"
          },
          "percent" : "100"
        }
      ],
      "manager": ["First name Last name"],
      "carrier": "Carrier Name",
      "device_location": "Location",
      "employee_number": "0123456789",
      "evergreen_date": "2021-10-19",
      "upgrade_cost": "123",
      "contract_expiry_date": "Expired",
      "contract_balance": "Unknown",
      "imei_number": "9876543210",
      "sim_number": "5432109876",
      "transfer_responsibility_etf": "12.24",
      "static_ip": null,
      "asset_tag": "34567",
      "account_number": "121212",
      "last_upgraded_date": "2019-01-01",
      "device_model_id": 1,
      "directory_push": true,
      "device_used_for": "Name",
      "redeployment_available": false
    }, {...}
  ]
}

Fail Response

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

HTTP Request

GET: /api/clients/devices

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	TRUE	Secret token for access to the API
since	Body	Integer	FALSE	filter devices by last update date since parameter in unix time

Query Response

Type: JSON

HTTP status code: 200 for Success and Fail cases, 500 for server erros

Success Response

Name	Type	Description
data	Array	Array of devices
data[0][username]	String	Username
data[0][number]	String	Number
data[0][customer_id]	String	Id of customer
data[0][device_id]	String	Id of device
data[0][status]	String	Device status, "active", "suspended" or "cancelled"
data[0][device_make_and_model]	String
data[0][device_make_name]	String	Device make name
data[0][device_email]	String	Email address
data[0][business_unit]	Array
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
data[0][employee_number]	String	Employee number
data[0][evergreen_date]	String	Evergreen date
data[0][upgrade_cost]	String
data[0][contract_expiry_date]	String	Contract expiration date
data[0][contract_balance]	String
data[0][imei_number]	String	Device IMEI number
data[0][sim_number]	String	Sim number
data[0][transfer_responsibility_etf]	String	Transfer Responsibility ETF
data[0][static_ip]	String	IP address
data[0][asset_tag]	String
data[0][account_number]	String
data[0][last_upgraded_date]	String	Last upgrade date
data[0][directory_push]	Boolean	Directory push
data[0][device_model_id]	Integer	Id of device model
data[0][device_used_for]	String	Used for
data[0][rate_plans]	String	Rate plans
data[0][device_initial_activation_date]	String	Initial activation date
data[0][device_contract_start_date]	String	Contract start date
data[0][eligibility_date]	String	Eligibility Date
data[0][redeployment_available]	Boolean	Redeployment Available

Fail Response

Name	Type	Description
message	String	Result description of the response

Synchronize lists of devices

Example:

curl -d "{\"data\": [{\"billing_account\":\"12345\",\"device_make\":\"iPhone\",\"number\":\"7809000000\",\"username\":\"Chuck N\", \"email\":\"a@example.com\", \"location\":\"Earth\", \"asset_tag\":\"34567\", \"employee_location\":\"Earth\", \"employee_title\":\"Job\", \"employee_number\":\"12345\", \"upgrade_cost\":\"123\", \"employment_status\":\"Active\", \"employment_status\":\"Active\", \"accounting_categories\" : [{ \"Account\" : \"123456\", \"Sub Account\" : \"012345\", \"percent\" : \"100\" }], \"manager\":\"Chuck N\", \"manager\":\"iPhone\", \"last_upgraded_date\":\"2019-01-01\" }]}" -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": 1,
  "results": {
    "7809000000": {
      "status": "created"
    },
    "7809000001": {
      "status": "updated"
    }
  }
}

Fail Response (sync)

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

Success Response (async)

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

Fail Response (async)

{
  "status": 500
}

HTTP Request

POST: /api/clients/devices/synchronize

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	TRUE	Secret token for access to the AP
data	Body	Array	TRUE	Array of devices 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	TRUE	Turn on/off async mode. If it is turned on, then perform synchronization asynchronously. Default: false.

Available device attributes in data param

Name	Type	Required?	Can be blank?	Description
number	String	TRUE	FALSE
username	String	TRUE for new devices	FALSE	“Last name, First name” will be transformed to “First name Last name” if value contains comma
email	String	FALSE	TRUE	Email address
location	String	FALSE	TRUE
asset_tag	String	FALSE	TRUE
billing_account	String	TRUE for new devices	TRUE	Number of the account
employee_location	String	FALSE	TRUE
employee_title	String	FALSE	TRUE	Employee job title
employee_number	String	FALSE	TRUE	Employee number
upgrade_cost	String	FALSE	TRUE
employment_status	String	FALSE	TRUE	Employee status
accounting_categories	Array	FALSE	TRUE	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.
manager	String	FALSE	TRUE	First and Last name of the manager
device_make	String	TRUE for new devices	FALSE	Name of the maker
last_upgraded_date	String	FALSE	TRUE	date in format yyyy-mm-dd
used_for	String	FALSE	TRUE	Used for

Query Response

Type: JSON

HTTP status code: 200 for Success and Fail cases, 500 for server errors

Response

Name	Type	Presence	Description
message	String	always	Result description of the response
job_id	Integer	always	ID of a created job (use it to get job status)
results	Hash	sync requests 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

Check devices synchronization job status

Example:

curl -d "{\"job_id\": \"1\"}" -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": {
    "7809000000": {
      "status": "created"
    },
    // ...
  }
}

Fail Response

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

HTTP Request

POST: /api/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 for Success and Fail cases, 500 for server erros

Name	Type	Description
status	String	Status of synchronization
results	Hash	Hash with results of synchronization

Change device status

Examples:

curl -d "{\"number\":\"7809000000\", \"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\":\"7809000000\", \"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": 1 }

Fail Response

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

HTTP Request

POST: /api/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	TRUE	required for suspended status. "Reduced Rate" or "Full Rate"
external_reference_number	Body	String	FALSE	External Reference Number

Query Response

Type: JSON

HTTP status code: 201 for Created and Fail cases, 422 for unprocessable entity, 500 for server errors

Name	Type	Description
id	Integer	id of created status update request

Employees API

This API is available for customers and provide abilities to read and synchronize employees.

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",
      "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 devices
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][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/clients/employees?page=1&since=1527450237

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	TRUE	Secret token for access to the API
page	Body	Integer	FALSE	Page number for pagination (100 items per page)
since	Body	Integer	FALSE	filter employees by last update date since parameter in unix time

Query Response

Type: JSON

HTTP status code: 200 for Success and Fail cases, 500 for server erros

Success Response

Name	Type	Description
data	Array	Array of employees

Fail Response

Name	Type	Description
message	String	Result description of the response

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": 1,
  "results": {
    "A100500": {
      "status": "created"
    }
  }
}

Fail Response (sync)

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

Success Response (async)

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

Fail Response (async)

{
  "status": 500
}

HTTP Request

POST: /api/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	TRUE	Turn on/off async mode. If it is turned on, then perform synchronization asynchronously. Default: false.
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
number	String	TRUE	FALSE	Unique employee number
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"
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	Number of seconds
terminated_date	Integer	FALSE	TRUE	Number of 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 for Success and Fail cases, 500 for server erros

Name	Type	Presence	Description
message	String	always	Result description of the response
job_id	Integer	always	ID of created job
results	Hash	sync requests only	Key - employee name, value - hash with status and maybe array of errors

Check synchronization job status

Example:

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

Success Response

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

Fail Response

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

HTTP Request

POST: /api/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 for Success and Fail cases, 500 for server erros

Name	Type	Description
status	String	Status of synchronization
results	Hash	Hash with results of synchronization

Accounting Categories API

This API is available for customers and provide abilities to read and synchronize accounting categories.

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",
      "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",
      "tax_jurisdiction": "tax jurisdiction",
      "additional_status": "additional status",
      "approval_managers": [
        {
          "name": "Mike Scott",
          "email": "mike@scott.com"
        }
      ]
    },
    {...}
  ]
}

Fail Response

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

HTTP Request

GET: /api/clients/accounting_categories

Query Parameters

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

Query Response

Type: JSON

HTTP status code: 200 for Success and Fail cases, 500 for server erros

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
data[0][description_2]	String
data[0][description_3]	String
data[0][description_4]	String
data[0][tax_jurisdiction]	String
data[0][additional_status]	String
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	Result description of the response

Synchronize lists of accounting categories

Example:

curl -d "{\"data\":[{\"accounting_type\":\"12345\",\"name\":\"Chuck N\",\"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\":\"12345\",\"name\":\"Chuck N\",\"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": 1,
  "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": 1,
  "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":  1
}

Fail Response (async)

{
  "status": 500
}

HTTP Request

POST: /api/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 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	TRUE	Turn on/off async mode. If it is turned on, then perform synchronization asynchronously. Default: false.
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	accounting type name
name	String	TRUE	FALSE	accounting category name
description	String	FALSE	TRUE
description_2	String	FALSE	TRUE
description_3	String	FALSE	TRUE
description_4	String	FALSE	TRUE
tax_jurisdiction	String	FALSE	TRUE
additional_status	String	FALSE	TRUE
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

Name or Email is required for attaching a manager to the accounting category

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 for Success and Fail cases, 500 for server erros

Name	Type	Presence	Description
message	String	always	Result description of the response
job_id	Integer	always	ID of a created job (use it to get job status)
results	Hash	sync requests 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)

Check synchronization status of accounting categories

Example:

curl -d "{\"job_id\": \"1\"}" -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": [ "This manager doesn't exist on this customer" ]
    },
    // ...
  }
}

HTTP Request

POST: /api/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 for Success and Fail cases, 500 for server erros

Name	Type	Description
status	String	Status of synchronization
results	Hash	Hash with results of synchronization

Hardware Ordering API

This API is available for customers and provide abilities to create orders.

Get list of customer hardware orders

Example:

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

Success Response

{
  "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"}
        },
      ],
      "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/clients/orders?page=1

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	TRUE	Secret token for access to the API
page	Body	Integer	FALSE	Page number for pagination (100 items per page)

Query Response

Type: JSON

HTTP status code: 200 for Success and Fail cases, 500 for server erros

Success Response

Name	Type	Description
data	Array	Array of orders

Fail Response

Name	Type	Description
message	String	Result description of the response

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/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	Body	Boolean	FALSE	Show Bell OrdersInfo. (Default: false)

Query Response

Type: JSON

HTTP status code: 200 for successful request, 404 for not found record, 500 for server errors

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

Attributes for an order

Name	Type	Description
uuid	Integer	Order ID
state	String	Order State (Possible values: "Configuration", "Waiting for approval", "Contact to the Dealer", "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 seperated 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	Shipping 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 Item state
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
reason	String	Reason for the device replacement (eligible_for_upgrade / broken / lost / other)
custom_reason	String	Reason details (required when reason attribute is set to other)
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

Response:
{
  "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 Attributes

Name	Type	Description
orders	Array	Bell Orders info. See Bell Info Order attributes.

Bell Info Order 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
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 Tem
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	Acessory name
waybill	String	Waybill
contract_term	String	Contract Tem
device_id	Integer	Device ID in our system
taxes	Hash	Accessories taxes
total	Float	Accessories total

Create Hardware Order

Example:

curl --location --request POST 'https://myserve.co/api/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",
    ...
  }
}

Fail Response

{ "status": "failed", "errors": ["Carrier can't be found", "Dealer can't be found"] }

HTTP Request

POST: /api/clients/orders

Query Parameters

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 abbriviation of the shipping province. If shipping.bell_api_city_id exists then the value is skipped
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 seperated 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	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
address2	String	FALSE	Address2
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	Attention
note	String	FALSE	Note

order_item attributes for a device replacement

Name	Type	Required	Description
product_id	Integer	TRUE	ordered product ID
color	String	FALSE	Color
number	String	TRUE	Device that going to be replaced
reason	String	TRUE	Reason for the device replacement (eligible_for_upgrade / broken / lost / other)
custom_reason	String	FALSE*	Reason details (*required when reason attribute is set to broken / lost / other)
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)
request_subtype	String	FALSE	request subtype
meta	Hash	FALSE	Additional order item information

order_item 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 city from bell API (NOTE: required for Bell Orders)
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 acessories info. See accessory attributes.
accounting_codes	Array	TRUE	Business unit. See accounting code attributes.
request_type	String	TRUE	request_type (new / replacement / accessory)
request_subtype	String	FALSE	request subtype
meta	Hash	FALSE	Additional order item information
port_request	Hash	FALSE	Port-In information. See port_request attributes. NOTE: if port_request present then city has no sense and would be nullified

order_item attributes for ordering only accesories

Name	Type	Required	Description
employee_name	String	TRUE	Employee name
employee_number	String	FALSE	Employee number
employee_email	String	FALSE	Employee email
accessories	Array	TRUE	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)
request_subtype	String	FALSE	request subtype
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 for Created Order, 422 for unprocessable entity, 500 for server errors

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

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/clients/hardware_ordering/accessories

Query Parameters

Name	Location	Type	Description
API_TOKEN	Header	String	Secret token for access to the API
product_id	Body	Integer	optional filter accessories by product id

Query Response

Type: JSON

HTTP status code: 200 for Success and Fail cases, 500 for server errors

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=Carrier

Success Response

{
  "data": [
    {
      "id":111,
      "name":"iPhone",
      "device_terms": [
        {
          "name":"no term",
          "price":"999.00",
          "description": "no term - $999.00"
        }
      ],
      "colors": ["white", "black"],
      "device_model_id": 1,
      "device_make": "iPhone",
      "carriers": ["Bell"]
    }, {...}
  ]
}

Fail Response

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

HTTP Request

GET: /api/clients/hardware_ordering/products?carrier=Carrier

Query Parameters

Name	Location	Type	Description
API_TOKEN	Header	String	Secret token for access to the API
carrier	Body	String	carrier name

Query Response

Type: JSON

HTTP status code: 200 for Success and Fail cases, 500 for server errors

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]	String	Term price
data[0][device_terms][0][description]	String	Term description
data[0][colors]	Array	Available colors
data[0][device_model_id]	String	device model id
data[0][device_make]	String	device make name
data[0][products]	String	Array of product carrier names

Fail Response

Name	Type	Description
message	String	Result description of the response

Get the list of Canadian cities

Example:

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

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/clients/hardware_ordering/cities?page=2

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 for Success and Fail cases, 500 for server errors

Success Response

Name	Type	Description
total_count	Integer	Total cities 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

SIM Card Changes API

This API is available for customers and provide abilities to read and create sim card changes requests.

Get status of SIM card change request

Examples:

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

Success Response

{ "status": "initial" }

Fail Respose

404, Not Found

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 for Success and Fail cases, 404 for not found error, 500 for server errors

Success Response

Name	Type	Description
status	String	sim card change request status

Fail Response

404, Not Found

Create new SIM card change request

Example:

curl -d "{\"number\":\"7809000000\",\"old_sim\":\"12345\",\"new_sim\":\"54321\"}" -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": 1 }

Fail Response

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

HTTP Request

POST: /api/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	device number
old_sim	Body	String	FALSE	old sim number
new_sim	Body	String	TRUE	new sim number
external_reference_number	Body	String	FALSE	External Reference Number

Query Response

Type: JSON

HTTP status code: 201 for Created and Fail cases, 422 for unprocessable entity, 500 for server errors

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

Tickets API

This API is available for customers and provide abilities to read and create tickets.

Get list of tickets

Example:

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

Success Response

{
  "data": [
    {
      "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

Query Response

Type: JSON

HTTP status code: 200 for Success and Fail cases, 500 for server errors

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/1

Success Response

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

Fail Respose

404, Not Found

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 for Success and Fail cases, 404 for not found error, 500 for server errors

Success Response

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

404, 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": 1,
  "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"]
  }
}

HTTP Request

POST: /api/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	TRUE	emails to notify after complete or cancel ticket

Query Response

Type: JSON

HTTP status code: 201 for Created and Fail cases, 422 for unprocessable entity, 500 for server errors

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
comment	String	Message when ticket comes to "canceled" or "completed"
status	String	Current ticket status "pending", "completed" or "cancelled"

Data Usage API

This API is available for customers and provide abilities to read total data usage.

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": "123456",
      "username": "Chuck N",
      "total_volume": 1024
    }, {...}
  ]
}

Fail Response

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

HTTP Request

GET: /api/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	Body	String	TRUE	business account number

Query Response

Type: JSON

HTTP status code: 200 for Success and Fail cases, 500 for server errors

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]	String	current month total data usage

Fail Response

Name	Type	Description
message	String	Result description of the response

In Month Data Usage API

This API is available for customers and provide abilities to read In Month data usage.

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=123456

Success Response

{
  "data": [
    {
      "date":'2019-01-01',
      "data":1024
    }, {...}
  ]
}

Fail Response

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

HTTP Request

GET: /api/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	Body	Integer	TRUE	device number

Query Response

Type: JSON

HTTP status code: 200 for Success and Fail cases, 500 for server errors

Success Response

Name	Type	Description
data	Array	Array of equipment orders
data[0][date]	String	usage date
data[0][data]	String	used data in bytes

Fail Response

Name	Type	Description
message	String	Result description of the response

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":1,
      "log_date":"2019-01-01'",
      "pool_size":1024,
      "pool_usage":1024
    }, {...}
  ]
}

Fail Response

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

HTTP Request

GET: /api/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 for Success and Fail cases, 500 for server errors

Success Response

Name	Type	Description
data	Array	Array of equipment orders
data[0][account_number]	String	business account number
data[0][billing_account_data_pool_id]	String
data[0][log_date]	String
data[0][pool_size]	String
data[0][pool_usage]	String

Fail Response

Name	Type	Description
message	String	Result description of the response

Wirelines API

This API is available for customers and provide abilities to read and synchronize wirelines.

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/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 for Success and Fail cases, 500 for server errors

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
data[0][location]	String
data[0][used_for]	String
data[0][service_address]	String
data[0][subtype]	String
data[0][warehouse]	String
data[0][wireline_account]	String

Fail Response

Name	Type	Description
message	String	Result description of the response

Synchronize lists of wirelines

Example:

curl -d "{\"data\": [{\"username\":\"username\",\"status\":\"active\",\"model\":\"Model\",\"email\":\"a@example.com\", \"email\":\"a@example.com\", \"employee_number\":\"12345\", \"location\":\"Earth\", \"contract_expiry_date\":\"2020-01-01\", \"description\":\"text\", \"wireline_account\":\"123456789\" }]}" -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": 1,
  "results": {
    "7809000000": {
      "status": "created"
    },
    "7809000001": {
      "status": "updated"
    }
  }
}

Fail Response (sync)

{
  "message": "Errors occurred during the perform",
  "job_id": 1,
  "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":  1
}

Fail Response (async)

{
  "status": 500
}

HTTP Request

POST: /api/clients/wirelines/synchronize

Query Parameters

Name	Location	Type	Required	Description
API_TOKEN	Header	String	TRUE	Secret token for access to the AP
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	TRUE	Turn on/off async mode. If it is turned on, then perform synchronization asynchronously. Default: false.

Available wireline attributes in data param

Name	Type	Required?	Can be blank?	Description
number	String	TRUE	FALSE
username	String	FALSE	FALSE	username
status	String	FALSE	FALSE	status
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
location	String	FALSE	TRUE
used_for	String	FALSE	FALSE
service_address	String	FALSE	FALSE
warehouse	String	FALSE	FALSE
wireline_account	String	TRUE for new wirelines	FALSE

Query Response

Type: JSON

HTTP status code: 200 for Success and Fail cases, 500 for server errors

Response

Name	Type	Presence	Description
message	String	always	Result description of the response
job_id	Integer	always	ID of a created job (use it to get job status)
results	Hash	sync requests 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

Check wirelines synchronization job status

Example:

curl -d "{\"job_id\": \"1\"}" -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"
    },
    // ...
  }
}

HTTP Request

POST: /api/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 for Success and Fail cases, 500 for server erros

Name	Type	Description
status	String	Status of synchronization
results	Hash	Hash with results of synchronization

Billing Data Lines API

This API is available for customers and provide abilities to read billing data lines

Get list of device billing data lines

Example:

curl -H API_TOKEN:XXXXXXXXXXXXXX https://myserve.co/api/v1/clients/billing_data_lines?page=1&number=123456789&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/clients/billing_data_lines?page=1&number=123456789&billing_account=12345

Query Parameters

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

Query Response

Type: JSON

HTTP status code: 200 for Success and Fail cases, 500 for server errors

Success Response

Name	Type	Description
data	Array	Array of billing data lines

Fail Response

Name	Type	Description
message	String	Result description of the response

Transfer of Responsibility API

This API is available for customers and provide abilities get information and create transfer of responsibility requests.

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
rate_plan_name	Body	String	FALSE	Carrier rate plan name
device_make	Body	String	TRUE	Device make to resolve carrier rate plan in case if '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 for Created and Fail cases, 422 for unprocessable entity, 500 for server errors

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

{
  "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

{
  "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

{
  "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

{
  "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 for Success and Fail cases, 404 Not Found error, 500 Server Error

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

404 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	No	Should 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	Boolean	No	To create a preapproved request set to 'preapproved'
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 Carrier

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 for Created and Fail cases, 422 for unprocessable entity, 500 for server errors

Name	Type	Description
admin_name	String	Administrator name
carrier_action	String	Carrier action
confirm_legal_name	String	Confirm legal name
date	String	Transfer 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	No	Should be 'business-to-business'
phone_number	Body	String	Yes	Device phone number
business_account_number	Body	String	Yes	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 for Created and Fail cases, 422 for unprocessable entity, 500 for server errors

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

{
  "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

{
  "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 for Success and Fail cases, 404 Not Found error, 500 Server Error

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

404 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"
}