NAV Navbar
shell

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"
    }, {...}
  ]
}

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

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"

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"
    }, {...}
  ]
}

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 Postal Code
data[0][province] String Province
data[0][employee_type] String Employee type

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 Postal Code
province String FALSE TRUE Province
employee_type String FALSE TRUE Employee type

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][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
name String FALSE Name
email String FALSE Name

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",
        "province": "SK",
        "attention": "Note"
      },
      "dealer_message": "dealer message",
      "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",
      "province": "SK",
      "attention": "Note"
    },
    "dealer_message": "dealer message",
    "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
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
province String Shipping province
attention String Shipping attention

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": "Bell Procurement Simplex (Non Chargeable)","requester_emails": ["requester.email@example.com"],"shipping_province": "AB","shipping_address": "100, 10000-123 St Edmonton Alberta ABCDEF","shipping_attention": "John Doe","dealer_message": "Color does not matter","order_items": [{"product_id": 3956,"color": "","device_term": {"name": "3 year term (16GB)","price": 0},"number": "7806000000","accessories": [{"id": 92462,"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"}],"port_request": {"authorized_first_name": "FirstName","authorized_last_name": "LastName","transfer_date": "yyyy-mm-dd","prev_carrier_account": "12345678","prev_carrier_name": "CarrierName"}}]}'

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 FALSE An abbriviation of the shipping province. If not provided it will be taken from the shipping_address field.
order_items Body Array TRUE An array containing ordered items information
dealer_message Body String FALSE Message to the dealer
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

shipping attributes

Name Type Required Description
company_name String TRUE Company name
address1 String TRUE Address1
address2 String TRUE Address2
bell_api_city_id Integer TRUE Bell API city id from Cities endpoint
postal_code String TRUE Postal code
postal_code String TRUE Postal code
phone_number String TRUE Telephone
attention String TRUE Attention
note String TRUE 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)
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 list of bell api cities

Example:

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

Success Response

{
  "data": [
    {
      "id":111,
      "name":"Toronto",
      "province_name":"Ontario"
    }, {...}
  ]
}

Fail Response

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

HTTP Request

`GET: /api/clients/hardware_ordering/cities

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 products
data[0][id] Integer ID
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

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,
      "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 },
      "cancellation_costs": 10.0,
      "taxes":  10.0,
      "total_charges":  10.0,
      "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
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
cancellation_costs Float Cancellation Costs
taxes Float Taxes
total_charges Float Total Charges
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 Of Responsibility API has 4 endpoints:

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

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

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