Guidion - API

‍

How to Use Our REST APIs

Guidion's APIs enable seamless communication between Guidion and its partners. These APIs allow for easy transmission of Customer and Ticket information, as well as providing on-demand updates on Ticket status.

With Guidion's services, partners can efficiently manage their operations and ensure smooth communication with customers.

We have two endpoints available, one for production and one for the test environment, the URLs are the following:

Production → https://api-prod.guidion.nl/

Test → https://api-test.guidion.nl

The following documentation references the test environment by default.

For a full list of available APIs check our Swagger documentation.

Working with Guidion APIs

The data model

The Guidion's Home system basically consists of two main objects, the Customer and the Ticket.

Where the Customer is the client of the Partner, the Ticket is the assignment that is given to Guidion by the Partner.

Every Customer can only exist once for every Partner, the unique identifier is the PartnerCustomerId. The PartnerCustomerId is the unique identifier for that client at the Partner side, shared with Guidion when creating a Customer via the API.

Note: Please consult your Guidion's Account Manager to determine the state in which you can handle the returned data as truth, and how to interpret all other data

You should only save data as ‘assignment completed’ if the Ticket has a Completed status OR when Pending Partner Approval is set to True.

If there are (contractual) agreements like KPI’s, based on data that you retrieve from our API, then please consult your Guidion's Account Manager on how/when data should be interpreted.

Authenticate with HTTP

For the REST API endpoints we use OAuth for authentication.

The first time you try to authenticate with the Guidion's APIs reach out to our development team and ask for a test account, once you receive your credentials you will be able to authenticate with our services.

In order to authenticate, select the environment base URL and follow this endpoint:

/oauth/client_credential/accesstoken?grant_type=client_credentials

Import this curl:‍

curl --location 'https://api-test.guidion.nl/oauth/client_credential/accesstoken?grant_type=client_credentials' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: CookieConsentPolicy=0:1; LSKey-c$CookieConsentPolicy=0:1' \
--data-urlencode 'client_secret=<YOUR_API_KEY_SECRET>' \
--data-urlencode 'client_id=<YOUR_API_KEY>'

  
curl --location 'https://api-test.guidion.nl/oauth/client_credential/accesstoken?grant_type=client_credentials' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: CookieConsentPolicy=0:1; LSKey-c$CookieConsentPolicy=0:1' \
--data-urlencode 'client_secret=' \
--data-urlencode 'client_id='

‍

Authenticate with Postman:

Request type: POST

URL: https://api-test.guidion.nl/oauth/client_credential/accesstoken?grant_type=client_credentials

Params:

key : grant_type

value: client_credentials

Authorization: Inherit auth from parent

Body: None

Client_secret : <YOUR_API_KEY_SECRET>

Client_id : <YOUR_API_KEY>

Content-type: application/x-www-form-urlencoded

‍

Customer APIs

Data structure within Guidion

For every customer that is sent from Partner to Guidion, one Account and a Contact are created in our system. Once this Account is created, its identifier, the Guidion's customerId will be provided and you will be able to use it for later updates.

Create a customer

When you want to create a customer in our system, use this API.
Your customer identifier, customer details, and address details are required. In case of a successful request, a customer will be created on our side.

Request type: POST

Endpoint: /v1/customers

Parameters: None

Required fields:

partnerCustomerId
lastName
postalCode
houseNumber
Email*
phoneNumber**
mobile**

* please use nomail@guidion.nl if the email address of the customer is unknown

** for phoneNumber and mobile, at least one of them should be filled

Request Body:

  
   
{
  "partnerCustomerId":"AS2343",
  "firstName": "Jack",
  "initials": "J",
  "middleName": "Dan",
  "lastName": "Johnson",
  "gender": "Female",
  "company": "company Name",
  "address": {
    "postalCode": "12345",
    "houseNumber": "2",
    "houseNumberExt": "A",
    "extraResidentInformation": "Second door on the right, past recception",
    "street": "Grüner Weg 6",
    "city": "Butzbach",
    "country": "germany",
    "state": "berlin"
  },
  "email": "guidion@example.com",
  "phoneNumber": "+31 612345678",
  "mobile": "+31 612345678",
  "otherPhone": "+31 612345678"
}  
 

{
"partnerCustomerId":"AS2343",
"firstName": "Jack",
"initials": "J",
"middleName": "Dan",
"lastName": "Johnson",
"gender": "Female",
"company": "company Name",
"address": {
"postalCode": "12345",
"houseNumber": "2",
"houseNumberExt": "A",
"extraResidentInformation": "Second door on the right, past recception",
"street": "Grüner Weg 6",
"city": "Butzbach",
"country": "germany",
"state": "berlin" },
"email": "guidion@example.com",
"phoneNumber": "+31 612345678",
"mobile": "+31 612345678",
"otherPhone": "+31 612345678"
}

‍

Responses:
201

{
"status": "201",
"customerId": "0011w00000ZJxLCAA1",
"message": "OK"
}

400

{
"status": "400",
"errorMessage": "Invalid format : /email"
}

‍

Update a customer

When you want to update a customer that you previously created in our system, use this API.
For example, you can update a phone number or some address details.

Request type: PUT

Endpoint: /v1/customers/{customerId}

Parameters: customerId

This is the Guidion's customerId generated and returned when consuming the create customer API API.

Request Body:

  
   
{
  "partnerCustomerId": "AS2343",
  "firstName": "Jack",
  "initials": "J",
  "middleName": "Dan",
  "lastName": "Johnson",
  "gender": "Female",
  "company": "company Name",
  "address": {
    "postalCode": "12345",
    "houseNumber": "2",
    "houseNumberExt": "A",
    "extraResidentInformation": "Second door on the right, past recception",
    "street": "Grüner Weg 6",
    "city": "Butzbach",
    "country": "germany",
    "state": "berlin"
  },
  "email": "guidion@example.com",
  "phoneNumber": "+31 612345678",
  "mobile": "+31 612345678",
  "otherPhone": "+31 612345678"
}  
 

‍

Responses:
201

{
"status": "201",
"customerId": "0011w00000ZJxLCAA1",
"message": "OK"
}

400

{
"status": "400",
"errorMessage": "Invalid format : /email"
}

‍

Ticket APIs

Data structure within Guidion

For every assignment that is issued from Partner to Guidion, one Ticket is created. Every ticket is related to one Contract. A ticket has a 3 layered data model, consisting of a Ticket, a Work Order and a Service Appointment.

In some scenarios Guidion could decide to generate 1 Ticket with multiple Work Orders. Therefore, when retrieving updates on your ticket, the response could contain multiple Work Orders with their Service Appointments. Guidion Digital, Guidion Business and the Partner will agree on the model to use for Partner’s work types.

Usually, a 1-1-1 model is chosen.

When one ticket is created by the Partner, this will create one Ticket, with one Work Order, with one Service Appointment.

Contract

A Contract determines the type of assignment Guidion will perform. A contract is related to the work that needs to be done, and what data can be inserted and will be collected by the Expert. List of available Contracts can be found on page 12

*Consult your Guidion Account Manager to agree on the Contracts that are being used.

Contract identifiers for Partner (contractExternalId)

Ticket / Case

The actual assignment, for example “ISP X Internet installation”. Internally this is referred to as a Case.

Every ticket can only have one Contract

Work Order

The Work Order contains the work that needs to be done to complete the assignment. On the Work Order we at least save the Work Order Line Items, the Products Required/Returned/Consumed, and all supplementary data needed for Guidion and the Expert to perform the work, and for the Partner to process the assignment after completion.

Service Appointment

The Service Appointment, which among others contains the appointment date and the assigned resource. In the API it’s simply known as Appointment

‍

Create a ticket

When you want to create a ticket, for example representing an installation request for a certain customer, use this API.

Provide the required information such as the Guidon customer Id and other request (ticket) details.

A list of additional services is available and can be added to the request on demand.

Request type: POST

Endpoint: /v2/tickets

Parameters: None

Required fields:

contractExternalId
customerId

‍

Request Body:

{
"contractExternalId": "2005",
"description": "description",
"customerId": "0011t00000XXXXXXXX",
"partnerTicketId": "1234ADC",
"earliestPermittedPlanDate": "2019-12-25T13:00:00Z",
"latestPermittedPlanDate": "2019-12-25T13:00:00Z",
"preferredPlanDate": "2019-12-25T13:00:00Z",
"leadTimeInDays": 2,
"isMigration": false,
"subject": "Installation",
"servicePageUrl": "http://example.com/servicepage",
"supplementaryInformation": {
"oilTankDisposal": "true"
},
"specifiedSchedulingWindow": "ALLDAY",
"additionalServices": [
[
{
"code": "EXAMPLE_1",
"quantity": 1,
"type": "WOLI",
"action": "ADD"
}
],
[
{
"code": "EXAMPLE_2",
"quantity": "1",
"type": "PRODUCT",
"action": "SET"
}
]
]
}

  
   
{
  "contractExternalId": "2005",
  "description": "description",
  "customerId": "0011t00000XXXXXXXX",
  "partnerTicketId": "1234ADC",
  "earliestPermittedPlanDate": "2019-12-25T13:00:00Z",
  "latestPermittedPlanDate": "2019-12-25T13:00:00Z",
  "preferredPlanDate": "2019-12-25T13:00:00Z",
  "leadTimeInDays": 2,
  "isMigration": false,
  "subject": "Installation",
  "servicePageUrl": "http://example.com/servicepage",
  "supplementaryInformation": {
    "oilTankDisposal": "true"
  },
  "specifiedSchedulingWindow": "ALLDAY",
  "additionalServices": [
    [
      {
        "code": "EXAMPLE_1",
        "quantity": 1,
        "type": "WOLI",
        "action": "ADD"
      }
    ],
    [
      {
        "code": "EXAMPLE_2",
        "quantity": 1,
        "type": "PRODUCT",
        "action": "SET"
      }
    ]
  ]
}  
 

‍

Responses:
201

{
"message": "Success",
"status": "201",
"tickets": [
{
"description": "Some random ticket description",
"reasonforCancellation": "Partner Canceled",
"whoCancelled": "Partner",
"hashId": "XXXXXXXX",
"selfserviceURL": "acc.afsprk.nl/t/XXXXXXXX?s=p",
"otherCancellationRemarks": "Klant niet bereikt na 3 belpogingen.",
"customerId": "0011w00000XXXXXXXX",
"partnerCustomerId": "GLA123",
"isMigration": false,
"leadTimeInDays": 3,
"externalId": "TK-51953",
"contractExternalId": "2021",
"partnerTicketId": "11111",
"supplementaryInformation": {
"IPAddress": "192.168.1.1",
"WifiCheckSuccessful": true
},
"lastModified": "2018-11-01T00:00:00Z",
"created": "2018-11-01T01:00:00Z",
"status": "New",
"closedDate": null,
"workOrders": [
{
"id": "00W000000aXXXXXXXX",
"managedServiceSettingsId": "a851v00000XXXXXXXX",
"subject": "DSL Installation",
"servicePage": "http://example.com/servicepage",
"expertComments": "Coffee was weak",
"status": "New",
"pendingPartnerApproval": true,
"fixCode": "FIX-1234",
"planCode": "11111",
"schedulingWindow": "Installaties + oplevering",
"appointments": [
{
"fixCodeId": "",
"scheduleStart": "2018-11-01T12:00:00Z",
"scheduleEnd": "2018-11-01T13:00:00Z",
"arrivalWindowStart": "2018-11-01T11:00:00Z",
"arrivalWindowEnd": "2018-11-01T13:00:00Z",
"customerNotHomePicture": "https://pic1-example.jpg",
"customerNotHomeDescription": "Some random description",
"status": "New"
}
],
"productsRequired": [
{
"productCode": "AAA-555",
"quantity": 1,
"productExternalId": "DSL_MODEM",
"productFamily": "Overig",
"id": "a710Y00000XXXXXXXX",
"productId": "01t0Y00000XXXXXXXX",
"name": "DSL Modem"
}
],
"productsConsumed": [
{
"productCode": "AAA-555",
"quantity": 1,
"productExternalId": "DSL_MODEM",
"productFamily": "Overig",
"name": "DSL Modem",
"type": "SERVICE",
"id": "a710Y00000XXXXXXXX",
"productId": "01t0Y00000XXXXXXXX",
"serialNumber": "745057128932983"
}
],
"productsReturned": [
{
"productCode": "AAA-555",
"quantity": 3,
"productExternalId": "P123",
"name": "Invisibility Cloak",
"type": "Loan",
"id": "a710Y000000jE97QAA",
"productId": "01t0Y00000XXXXXXXX",
"serialNumber": "55378008",
"productState": "Defect, hardware"
}
],
"workOrderLineItems": [
{
"templateId": "a8b0700000XXXXXXXX",
"templateExternalId": "DSL_INSTALL",
"origin": "CUSTOM",
"subject": "A simple DSL Model installation",
"id": "1WL3M00000XXXXXXXX",
"lineItemNumber": "00000001",
"durationType": "Minutes",
"duration": 30
}
]
}
]
}
]
}

  
   
{
  "message": "Success",
  "status": "201",
  "tickets": [
    {
      "description": "Some random ticket description",
      "reasonforCancellation": "Partner Canceled",
      "whoCancelled": "Partner",
      "hashId": "XXXXXXXX",
      "selfserviceURL": "acc.afsprk.nl/t/XXXXXXXX?s=p",
      "otherCancellationRemarks": "Klant niet bereikt na 3 belpogingen.",
      "customerId": "0011w00000XXXXXXXX",
      "partnerCustomerId": "GLA123",
      "isMigration": false,
      "leadTimeInDays": 3,
      "externalId": "TK-51953",
      "contractExternalId": "2021",
      "partnerTicketId": "11111",
      "supplementaryInformation": {
        "IPAddress": "192.168.1.1",
        "WifiCheckSuccessful": true
      },
      "lastModified": "2018-11-01T00:00:00Z",
      "created": "2018-11-01T01:00:00Z",
      "status": "New",
      "closedDate": null,
      "workOrders": [
        {
          "id": "00W000000aXXXXXXXX",
          "managedServiceSettingsId": "a851v00000XXXXXXXX",
          "subject": "DSL Installation",
          "servicePage": "http://example.com/servicepage",
          "expertComments": "Coffee was weak",
          "status": "New",
          "pendingPartnerApproval": true,
          "fixCode": "FIX-1234",
          "planCode": "11111",
          "schedulingWindow": "Installaties + oplevering",
          "appointments": [
            {
              "fixCodeId": "",
              "scheduleStart": "2018-11-01T12:00:00Z",
              "scheduleEnd": "2018-11-01T13:00:00Z",
              "arrivalWindowStart": "2018-11-01T11:00:00Z",
              "arrivalWindowEnd": "2018-11-01T13:00:00Z",
              "customerNotHomePicture": "https://pic1-example.jpg",
              "customerNotHomeDescription": "Some random description",
              "status": "New"
            }
          ],
          "productsRequired": [
            {
              "productCode": "AAA-555",
              "quantity": 1,
              "productExternalId": "DSL_MODEM",
              "productFamily": "Overig",
              "id": "a710Y00000XXXXXXXX",
              "productId": "01t0Y00000XXXXXXXX",
              "name": "DSL Modem"
            }
          ],
          "productsConsumed": [
            {
              "productCode": "AAA-555",
              "quantity": 1,
              "productExternalId": "DSL_MODEM",
              "productFamily": "Overig",
              "name": "DSL Modem",
              "type": "SERVICE",
              "id": "a710Y00000XXXXXXXX",
              "productId": "01t0Y00000XXXXXXXX",
              "serialNumber": "745057128932983"
            }
          ],
          "productsReturned": [
            {
              "productCode": "AAA-555",
              "quantity": 3,
              "productExternalId": "P123",
              "name": "Invisibility Cloak",
              "type": "Loan",
              "id": "a710Y000000jE97QAA",
              "productId": "01t0Y00000XXXXXXXX",
              "serialNumber": "55378008",
              "productState": "Defect, hardware"
            }
          ],
          "workOrderLineItems": [
            {
              "templateId": "a8b0700000XXXXXXXX",
              "templateExternalId": "DSL_INSTALL",
              "origin": "CUSTOM",
              "subject": "A simple DSL Model installation",
              "id": "1WL3M00000XXXXXXXX",
              "lineItemNumber": "00000001",
              "durationType": "Minutes",
              "duration": 30
            }
          ]
        }
      ]
    }
  ]
}  
 

400

{
"status": "400",
"errorMessage": "contractExternalId does not exist"
}

‍

Retrieve a list of tickets in a defined time range

When you want to retrieve information for multiple ticket having the same contract type, use this API.

This API uses pagination so you will have to provide the number of pages, the number of records you want to see on each page, and a time range.

Other possible parameters are listed below.

Request type: GET

Endpoint: /v2/tickets

Parameters: lastModifiedFrom, lastModifiedTo, createdFrom, createdTo, contractExternalId

Headers will provide 4 integers, Record-Count, Page-Count, Page-No, and Page-Size

‍

Responses:
200

{
"message": "Success",
"status": "200",
"tickets": [
{
"description": "Some random ticket description",
"reasonforCancellation": "Partner Canceled",
"whoCancelled": "Partner",
"hashId": "XXXXXXXX",
"selfserviceURL": "acc.afsprk.nl/t/XXXXXXXX?s=p",
"otherCancellationRemarks": "Klant niet bereikt na 3 belpogingen.",
"customerId": "0011w0000XXXXXXXX",
"partnerCustomerId": "GLA123",
"isMigration": false,
"leadTimeInDays": 3,
"externalId": "TK-51953",
"contractExternalId": "2021",
"partnerTicketId": "83913",
"supplementaryInformation": {
"IPAddress": "192.168.1.1",
"WifiCheckSuccessful": true
},
"lastModified": "2018-11-01T00:00:00Z",
"created": "2018-11-01T00:00:00Z",
"status": "New",
"closedDate": null,
"workOrders": [
{
"id": "00W000000aXXXXXXXX",
"managedServiceSettingsId": "a851v00000XXXXXXXX",
"subject": "DSL Installation",
"servicePage": "http://example.com/servicepage",
"expertComments": "Coffee was weak",
"status": "New",
"pendingPartnerApproval": true,
"fixCode": "FIX-1234",
"planCode": "11111",
"schedulingWindow": "Installaties + oplevering",
"appointments": [
{
"fixCodeId": "",
"scheduleStart": "2018-11-01T12:00:00Z",
"scheduleEnd": "2018-11-01T13:00:00Z",
"arrivalWindowStart": "2018-11-01T11:00:00Z",
"arrivalWindowEnd": "2018-11-01T13:00:00Z",
"customerNotHomePicture": "https://pic1-example.jpg",
"customerNotHomeDescription": "Some random description",
"status": "New"
}
],
"productsRequired": [
{
"productCode": "AAA-555",
"quantity": 1,
"productExternalId": "DSL_MODEM",
"productFamily": "Overig",
"id": "a710Y00000XXXXXXXX",
"productId": "01t0Y0000XXXXXXXX",
"name": "DSL Modem"
}
],
"productsConsumed": [
{
"productCode": "AAA-555",
"quantity": 1,
"productExternalId": "DSL_MODEM",
"productFamily": "Overig",
"name": "DSL Modem",
"type": "SERVICE",
"id": "a710Y0000XXXXXXXX",
"productId": "01t0Y0000XXXXXXXX",
"serialNumber": "745057128932983" } ],
"productsReturned": [
{
"productCode": "AAA-555",
"quantity": 3,
"productExternalId": "P123",
"name": "Invisibility Cloak",
"type": "Loan",
"id": "a710Y00000XXXXXXXX",
"productId": "01t0Y00000XXXXXXXX",
"serialNumber": "55378008",
"productState": "Defect, hardware"
}
],
"workOrderLineItems": [
{
"templateId": "a8b0700000XXXXXXXX",
"templateExternalId": "DSL_INSTALL",
"origin": "CUSTOM",
"subject": "A simple DSL Model installation",
"id": "1WL3M00000XXXXXXXX",
"lineItemNumber": "00000001",
"durationType": "Minutes",
"duration": 30
}
]
}
]
}
]
}

  
   
{
  "message": "Success",
  "status": "200",
  "tickets": [
    {
      "description": "Some random ticket description",
      "reasonforCancellation": "Partner Canceled",
      "whoCancelled": "Partner",
      "hashId": "XXXXXXXX",
      "selfserviceURL": "acc.afsprk.nl/t/XXXXXXXX?s=p",
      "otherCancellationRemarks": "Klant niet bereikt na 3 belpogingen.",
      "customerId": "0011w0000XXXXXXXX",
      "partnerCustomerId": "GLA123",
      "isMigration": false,
      "leadTimeInDays": 3,
      "externalId": "TK-51953",
      "contractExternalId": "2021",
      "partnerTicketId": "83913",
      "supplementaryInformation": {
        "IPAddress": "192.168.1.1",
        "WifiCheckSuccessful": true
      },
      "lastModified": "2018-11-01T00:00:00Z",
      "created": "2018-11-01T01:00:00Z",
      "status": "New",
      "closedDate": null,
      "workOrders": [
        {
          "id": "00W000000aXXXXXXXX",
          "managedServiceSettingsId": "a851v00000XXXXXXXX",
          "subject": "DSL Installation",
          "servicePage": "http://example.com/servicepage",
          "expertComments": "Coffee was weak",
          "status": "New",
          "pendingPartnerApproval": true,
          "fixCode": "FIX-1234",
          "planCode": "11111",
          "schedulingWindow": "Installaties + oplevering",
          "appointments": [
            {
              "fixCodeId": "",
              "scheduleStart": "2018-11-01T12:00:00Z",
              "scheduleEnd": "2018-11-01T13:00:00Z",
              "arrivalWindowStart": "2018-11-01T11:00:00Z",
              "arrivalWindowEnd": "2018-11-01T13:00:00Z",
              "customerNotHomePicture": "https://pic1-example.jpg",
              "customerNotHomeDescription": "Some random description",
              "status": "New"
            }
          ],
          "productsRequired": [
            {
              "productCode": "AAA-555",
              "quantity": 1,
              "productExternalId": "DSL_MODEM",
              "productFamily": "Overig",
              "id": "a710Y00000XXXXXXXX",
              "productId": "01t0Y0000XXXXXXXX",
              "name": "DSL Modem"
            }
          ],
          "productsConsumed": [
            {
              "productCode": "AAA-555",
              "quantity": 1,
              "productExternalId": "DSL_MODEM",
              "productFamily": "Overig",
              "name": "DSL Modem",
              "type": "SERVICE",
              "id": "a710Y0000XXXXXXXX",
              "productId": "01t0Y0000XXXXXXXX",
              "serialNumber": "745057128932983"
            }
          ],
          "productsReturned": [
            {
              "productCode": "AAA-555",
              "quantity": 3,
              "productExternalId": "P123",
              "name": "Invisibility Cloak",
              "type": "Loan",
              "id": "a710Y00000XXXXXXXX",
              "productId": "01t0Y00000XXXXXXXX",
              "serialNumber": "55378008",
              "productState": "Defect, hardware"
            }
          ],
          "workOrderLineItems": [
            {
              "templateId": "a8b0700000XXXXXXXX",
              "templateExternalId": "DSL_INSTALL",
              "origin": "CUSTOM",
              "subject": "A simple DSL Model installation",
              "id": "1WL3M00000XXXXXXXX",
              "lineItemNumber": "00000001",
              "durationType": "Minutes",
              "duration": 30
            }
          ]
        }
      ]
    }
  ]
}  
 

400

{
"status": "400",
"errorMessage": "Last modified date range is too large"
}

‍

Update a ticket

When you want to update any information regarding a ticket, use this API.

Request type: PUT

Endpoint: /v2/tickets/{externalId}

Parameters: externalId to the existing ticket, that you provided when creating the ticket initially

‍

Request Body:

{
"contractExternalId": "2005",
"description": "description",
"customerId": "0011t000007aeCwAAI",
"partnerTicketId": "1234ADC",
"earliestPermittedPlanDate": "2019-12-25T13:00:00Z",
"latestPermittedPlanDate": "2019-12-25T13:00:00Z",
"preferredPlanDate": "2019-12-25T13:00:00Z",
"leadTimeInDays": 2,
"isMigration": false,
"subject": "Installation",
"servicePageUrl": "http://example.com/servicepage",
"supplementaryInformation": {
"oilTankDisposal": "true"
},
"specifiedSchedulingWindow": "ALLDAY",
"additionalServices": [
[
{
"code": "EXAMPLE_1",
"quantity": 1,
"type": "WOLI",
"action": "ADD"
}
],
[
{
"code": "EXAMPLE_2",
"quantity": 1,
"type": "PRODUCT",
"action": "SET"
}
]
]
}

  
   
{
  "contractExternalId": "2005",
  "description": "description",
  "customerId": "0011t000007aeCwAAI",
  "partnerTicketId": "1234ADC",
  "earliestPermittedPlanDate": "2019-12-25T13:00:00Z",
  "latestPermittedPlanDate": "2019-12-25T13:00:00Z",
  "preferredPlanDate": "2019-12-25T13:00:00Z",
  "leadTimeInDays": 2,
  "isMigration": false,
  "subject": "Installation",
  "servicePageUrl": "http://example.com/servicepage",
  "supplementaryInformation": {
    "oilTankDisposal": "true"
  },
  "specifiedSchedulingWindow": "ALLDAY",
  "additionalServices": [
    [
      {
        "code": "EXAMPLE_1",
        "quantity": 1,
        "type": "WOLI",
        "action": "ADD"
      }
    ],
    [
      {
        "code": "EXAMPLE_2",
        "quantity": 1,
        "type": "PRODUCT",
        "action": "SET"
      }
    ]
  ]
}  
 

‍

Responses:
201

{
"message": "Success",
"status": "201",
"tickets": [
{
"description": "Some random ticket description",
"reasonforCancellation": "Partner Canceled",
"whoCancelled": "Partner",
"hashId": "XXXXXXXX",
"selfserviceURL": "acc.afsprk.nl/t/XXXXXXXX?s=p",
"otherCancellationRemarks": "Klant niet bereikt na 3 belpogingen.",
"customerId": "0011w0000XXXXXXXX",
"partnerCustomerId": "GLA123",
"isMigration": false,
"leadTimeInDays": 3,
"externalId": "TK-123123",
"contractExternalId": "1111",
"partnerTicketId": "11111",
"supplementaryInformation": {
"IPAddress": "192.168.1.1",
"WifiCheckSuccessful": true
},
"lastModified": "2018-11-01T00:00:00Z",
"created": "2018-11-01T01:00:00Z",
"status": "New",
"closedDate": null,
"workOrders": [
{
"id": "00W00000XXXXXXXX",
"managedServiceSettingsId": "a851v00000XXXXXXXX",
"subject": "DSL Installation",
"servicePage": "http://example.com/servicepage",
"expertComments": "Coffee was weak",
"status": "New",
"pendingPartnerApproval": true,
"fixCode": "FIX-1234",
"planCode": "11111",
"schedulingWindow": "Installaties + oplevering",
"appointments": [
{
"fixCodeId": "",
"scheduleStart": "2018-11-01T12:00:00Z",
"scheduleEnd": "2018-11-01T13:00:00Z",
"arrivalWindowStart": "2018-11-01T11:00:00Z",
"arrivalWindowEnd": "2018-11-01T13:00:00Z",
"customerNotHomePicture": "https://pic1-example.jpg",
"customerNotHomeDescription": "Some random description",
"status": "New"
}
],
"productsRequired": [
{
"productCode": "AAA-555",
"quantity": 1,
"productExternalId": "EXAMPLE_1",
"productFamily": "Overig",
"id": "a710Y00000XXXXXXXX",
"productId": "01t0Y0000XXXXXXXX",
"name": "DSL Modem"
}
],
"productsConsumed": [
{
"productCode": "AAA-555",
"quantity": 1,
"productExternalId": "EXAMPLE_2",
"productFamily": "Overig",
"name": "DSL Modem",
"type": "SERVICE",
"id": "a710Y00000XXXXXXXX",
"productId": "01t0Y00000XXXXXXXX",
"serialNumber": "745057128932983"
}
],
"productsReturned": [
{
"productCode": "AAA-555",
"quantity": 3,
"productExternalId": "P123",
"name": "Invisibility Cloak",
"type": "Loan",
"id": "a710Y00000XXXXXXXX",
"productId": "01t0Y0000XXXXXXXX",
"serialNumber": "55378008",
"productState": "Defect, hardware"
}
],
"workOrderLineItems": [
{
"templateId": "a8b0700000XXXXXXXX",
"templateExternalId": "EXAMPLE_3",
"origin": "CUSTOM",
"subject": "A simple DSL Model installation",
"id": "1WL3M00000XXXXXXXX",
"lineItemNumber": "00000001",
"durationType":
"Minutes",
"duration": 30
}
]
}
]
}
]
}

  
   
{
  "message": "Success",
  "status": "201",
  "tickets": [
    {
      "description": "Some random ticket description",
      "reasonforCancellation": "Partner Canceled",
      "whoCancelled": "Partner",
      "hashId": "XXXXXXXX",
      "selfserviceURL": "acc.afsprk.nl/t/XXXXXXXX?s=p",
      "otherCancellationRemarks": "Klant niet bereikt na 3 belpogingen.",
      "customerId": "0011w0000XXXXXXXX",
      "partnerCustomerId": "GLA123",
      "isMigration": false,
      "leadTimeInDays": 3,
      "externalId": "TK-123123",
      "contractExternalId": "1111",
      "partnerTicketId": "11111",
      "supplementaryInformation": {
        "IPAddress": "192.168.1.1",
        "WifiCheckSuccessful": true
      },
      "lastModified": "2018-11-01T00:00:00Z",
      "created": "2018-11-01T01:00:00Z",
      "status": "New",
      "closedDate": null,
      "workOrders": [
        {
          "id": "00W00000XXXXXXXX",
          "managedServiceSettingsId": "a851v00000XXXXXXXX",
          "subject": "DSL Installation",
          "servicePage": "http://example.com/servicepage",
          "expertComments": "Coffee was weak",
          "status": "New",
          "pendingPartnerApproval": true,
          "fixCode": "FIX-1234",
          "planCode": "11111",
          "schedulingWindow": "Installaties + oplevering",
          "appointments": [
            {
              "fixCodeId": "",
              "scheduleStart": "2018-11-01T12:00:00Z",
              "scheduleEnd": "2018-11-01T13:00:00Z",
              "arrivalWindowStart": "2018-11-01T11:00:00Z",
              "arrivalWindowEnd": "2018-11-01T13:00:00Z",
              "customerNotHomePicture": "https://pic1-example.jpg",
              "customerNotHomeDescription": "Some random description",
              "status": "New"
            }
          ],
          "productsRequired": [
            {
              "productCode": "AAA-555",
              "quantity": 1,
              "productExternalId": "EXAMPLE_1",
              "productFamily": "Overig",
              "id": "a710Y00000XXXXXXXX",
              "productId": "01t0Y0000XXXXXXXX",
              "name": "DSL Modem"
            }
          ],
          "productsConsumed": [
            {
              "productCode": "AAA-555",
              "quantity": 1,
              "productExternalId": "EXAMPLE_2",
              "productFamily": "Overig",
              "name": "DSL Modem",
              "type": "SERVICE",
              "id": "a710Y00000XXXXXXXX",
              "productId": "01t0Y00000XXXXXXXX",
              "serialNumber": "745057128932983"
            }
          ],
          "productsReturned": [
            {
              "productCode": "AAA-555",
              "quantity": 3,
              "productExternalId": "P123",
              "name": "Invisibility Cloak",
              "type": "Loan",
              "id": "a710Y00000XXXXXXXX",
              "productId": "01t0Y0000XXXXXXXX",
              "serialNumber": "55378008",
              "productState": "Defect, hardware"
            }
          ],
          "workOrderLineItems": [
            {
              "templateId": "a8b0700000XXXXXXXX",
              "templateExternalId": "EXAMPLE_3",
              "origin": "CUSTOM",
              "subject": "A simple DSL Model installation",
              "id": "1WL3M00000XXXXXXXX",
              "lineItemNumber": "00000001",
              "durationType": "Minutes",
              "duration": 30
            }
          ]
        }
      ]
    }
  ]
}  
 

400

{
"status": "400",
"errorMessage": "contractExternalId does not exist"
}

‍

Retrieve information for a specific ticket

When you want to get data for a specific ticket, for example to check its status, use this API.

Request type: GET

Endpoint: /v2/tickets/{externalId}

Parameters: externalId to the existing ticket, that you provided when creating the ticket initially

‍

Responses:
200

{
"message": "Success",
"status": "200",
"tickets": [
{
"description": "Some random ticket description",
"reasonforCancellation": "Partner Canceled",
"whoCancelled": "Partner",
"hashId": "XXXXXXXX",
"selfserviceURL": "acc.afsprk.nl/t/XXXXXXXX?s=p",
"otherCancellationRemarks": "Klant niet bereikt na 3 belpogingen.",
"customerId": "0011w0000XXXXXXXX",
"partnerCustomerId": "GLA123",
"isMigration": false,
"leadTimeInDays": 3,
"externalId": "TK-123123",
"contractExternalId": "1111",
"partnerTicketId": "11111",
"supplementaryInformation": {
"IPAddress": "192.168.1.1",
"WifiCheckSuccessful": true
},
"lastModified": "2018-11-01T00:00:00Z",
"created": "2018-11-01T01:00:00Z",
"status": "New",
"closedDate": null,
"workOrders": [
{
"id": "00W00000XXXXXXXX",
"managedServiceSettingsId": "a851v00000XXXXXXXX",
"subject": "DSL Installation",
"servicePage": "http://example.com/servicepage",
"expertComments": "Coffee was weak",
"status": "New",
"pendingPartnerApproval": true,
"fixCode": "FIX-1234",
"planCode": "11111",
"schedulingWindow": "Installaties + oplevering",
"appointments": [
{
"fixCodeId": "",
"scheduleStart": "2018-11-01T12:00:00Z",
"scheduleEnd": "2018-11-01T13:00:00Z",
"arrivalWindowStart": "2018-11-01T11:00:00Z",
"arrivalWindowEnd": "2018-11-01T13:00:00Z",
"customerNotHomePicture": "https://pic1-example.jpg",
"customerNotHomeDescription": "Some random description",
"status": "New"
}
],
"productsRequired": [
{
"productCode": "AAA-555",
"quantity": 1,
"productExternalId": "EXAMPLE_1",
"productFamily": "Overig",
"id": "a710Y00000XXXXXXXX",
"productId": "01t0Y0000XXXXXXXX",
"name": "DSL Modem"
}
],
"productsConsumed": [
{
"productCode": "AAA-555",
"quantity": 1,
"productExternalId": "EXAMPLE_2",
"productFamily": "Overig",
"name": "DSL Modem",
"type": "SERVICE",
"id": "a710Y00000XXXXXXXX",
"productId": "01t0Y00000XXXXXXXX",
"serialNumber": "745057128932983"
}
],
"productsReturned": [
{
"productCode": "AAA-555",
"quantity": 3,
"productExternalId": "P123",
"name": "Invisibility Cloak",
"type": "Loan",
"id": "a710Y00000XXXXXXXX",
"productId": "01t0Y0000XXXXXXXX",
"serialNumber": "55378008",
"productState": "Defect, hardware"
}
],
"workOrderLineItems": [
{
"templateId": "a8b0700000XXXXXXXX",
"templateExternalId": "EXAMPLE_3",
"origin": "CUSTOM",
"subject": "A simple DSL Model installation",
"id": "1WL3M00000XXXXXXXX",
"lineItemNumber": "00000001",
"durationType":
"Minutes",
"duration": 30
}
]
}
]
}
]
}

  
   
{
  "message": "Success",
  "status": "200",
  "tickets": [
    {
      "description": "Some random ticket description",
      "reasonforCancellation": "Partner Canceled",
      "whoCancelled": "Partner",
      "hashId": "XXXXXXXX",
      "selfserviceURL": "acc.afsprk.nl/t/XXXXXXXX?s=p",
      "otherCancellationRemarks": "Klant niet bereikt na 3 belpogingen.",
      "customerId": "0011w00000XXXXXXXX",
      "partnerCustomerId": "GLA123",
      "isMigration": false,
      "leadTimeInDays": 3,
      "externalId": "TK-51953",
      "contractExternalId": "2021",
      "partnerTicketId": "11111",
      "supplementaryInformation": {
        "IPAddress": "192.168.1.1",
        "WifiCheckSuccessful": true
      },
      "lastModified": "2018-11-01T00:00:00Z",
      "created": "2018-11-01T01:00:00Z",
      "status": "New",
      "closedDate": null,
      "workOrders": [
        {
          "id": "00W000000aXXXXXXXX",
          "managedServiceSettingsId": "a851v00000XXXXXXXX",
          "subject": "DSL Installation",
          "servicePage": "http://example.com/servicepage",
          "expertComments": "Coffee was weak",
          "status": "New",
          "pendingPartnerApproval": true,
          "fixCode": "FIX-1234",
          "planCode": "11111",
          "schedulingWindow": "Installaties + oplevering",
          "appointments": [
            {
              "fixCodeId": "",
              "scheduleStart": "2018-11-01T12:00:00Z",
              "scheduleEnd": "2018-11-01T13:00:00Z",
              "arrivalWindowStart": "2018-11-01T11:00:00Z",
              "arrivalWindowEnd": "2018-11-01T13:00:00Z",
              "customerNotHomePicture": "https://pic1-example.jpg",
              "customerNotHomeDescription": "Some random description",
              "status": "New"
            }
          ],
          "productsRequired": [
            {
              "productCode": "AAA-555",
              "quantity": 1,
              "productExternalId": "EXAMPLE_1",
              "productFamily": "Overig",
              "id": "a710Y00000XXXXXXXX",
              "productId": "01t0Y00000XXXXXXXX",
              "name": "DSL Modem"
            }
          ],
          "productsConsumed": [
            {
              "productCode": "AAA-555",
              "quantity": 1,
              "productExternalId": "EXAMPLE_2",
              "productFamily": "Overig",
              "name": "DSL Modem",
              "type": "SERVICE",
              "id": "a710Y00000XXXXXXXX",
              "productId": "01t0Y00000XXXXXXXX",
              "serialNumber": "745057128932983"
            }
          ],
          "productsReturned": [
            {
              "productCode": "AAA-555",
              "quantity": 3,
              "productExternalId": "P123",
              "name": "Invisibility Cloak",
              "type": "Loan",
              "id": "a710Y00000XXXXXXXX",
              "productId": "01t0Y00000XXXXXXXX",
              "serialNumber": "55378008",
              "productState": "Defect, hardware"
            }
          ],
          "workOrderLineItems": [
            {
              "templateId": "a8b0700000XXXXXXXX",
              "templateExternalId": "EXAMPLE_1",
              "origin": "CUSTOM",
              "subject": "A simple DSL Model installation",
              "id": "1WL3M00000XXXXXXXX",
              "lineItemNumber": "00000001",
              "durationType": "Minutes",
              "duration": 30
            }
          ]
        }
      ]
    }
  ]
}  
 

400

{
"status": "400",
"errorMessage": "Unable to find record"
}

‍

Data structure of supplementary informations

Supplementary fields

We use supplementary fields as a flexible layer on our data model to store data that is specific to one Contract.

Each Contract has its own set of Supplementary Fields. If you require a change for the supplementary fields, please consult your Guidion Account Manager or Customer Success Manager.

Legacy FreeFields are mapped to our new Supplementary Field Api Key or a fixed field on the Ticket.

We distinguish two types of Supplementary Fields; Partner to Guidion and Guidion to Partner, respectively Input and Output.

Partner Status Codes

To offer an easy way of checking the overall status of a ticket, we use Partner Status Codes, known as Plan codes and Fix codes.

Each visit type (contract) can have its own predefined list of codes.

Plan Codes

These codes tell you what the pre-visit status of a ticket is. Like ‘customer not reached’ or ‘left voicemail’. Currently these fields are legacy as we merge all result codes to the Fix Code field.

Fix Codes

These codes tell the result of a visit.

All codes are predefined by Guidion and the Partner. Consult your Guidion Account Manager or Customer Success Manager if you need adjustments or clarifications on these codes.

Products

Guidion shares most product transactions via the API. A product can be hardware or a service. By providing insight we try to offer maximum transparency towards our partners so that they for example have real time insight in financial transactions and know exactly which product is installed at which customer.

If known, we will use your own Product Id’s on the External Id, at least for hardware. Please share your product id’s with Guidion for maximum efficiency.

‍Products Consumed

Each line represents a service or product item (hardware) that has been ‘consumed’ at the customer. If applicable we will also share serial numbers, product family and type.

Products Returned

Each line represents a product item (hardware) that has been returned from Customer to Expert. If applicable we will also share serial numbers, product family and type.

We also provide the ‘state’ of the returned product if applicable. There is a predefined list of possible values for this field, check with our devs for more information.

Products Required

On the GET response you can check what products we’ve set as required for our Experts. Each line represents a product item or a service.

The External Id is on “productExternalId”.

Table of contents

How to Use Our REST APIs

Working with Guidion APIs

The data model

Authenticate with HTTP

Customer APIs

Data structure within Guidion

Create a customer

Update a customer

Ticket APIs

Data structure within Guidion

Contract

Ticket / Case

Work Order

Service Appointment

Create a ticket

Retrieve a list of tickets in a defined time range

Update a ticket

Retrieve information for a specific ticket

Data structure of supplementary informations

Supplementary fields

Partner Status Codes

Plan Codes

Fix Codes

Products

‍Products Consumed

Products Returned

Products Required