July 16, 2020 16:46
Updated

Summary

Requirements

All API calls require a dedicated JSON Web Token (JWT). These are created when a user with a dedicated mobile resource logs in to the application. If you are using the API for programmatic queries, it is best to create a dedicated user for the JWT as this gets reset each time the user logs in.

Endpoint

/rest/costs/addCost

POST

Adds a cost to a job.

File Format Spec

List of included fields

Field Name	Data Type	Mandatory?	Description
`jobRef`	Char(20)	Yes if `jobClientRef` not provided	The Oneserve job reference
`jobClientRef`	Char(50)	Yes if `jobRef` not provided	The job client reference
`clientId`	Integer	Yes if `jobRef` not provided	The ID of the client on the job
`costTypeId`	Char(50)	Yes	The ID of the job cost type in Oneserve
`description`	Text (255)	Yes	The job cost description
`supplierId`	Integer	No	The ID of the team assigned to the cost
`resourceId`	Integer	No	The ID of the resource assigned to the cost
`unit`	Integer	Yes	The ID of the UOM used for the job cost
`postingType`	Integer	Yes	1 - Estimate 2 - Actual 3 - Expected
`quantity`	Decimal	Yes	The quantity of the cost
`date`	Date	Yes	Financial Transaction Date (mm/dd/yyyy)
`inputDate`	Date	No	The date at which the cost was input (defaults to current date)
`taxType`	Integer	Yes	The ID of the tax type
`unitCost`	Decimal	Yes	The cost of the unit
`unitSales`	Decimal	Yes	The sales value of the unit

Request Representations

JSON payload example

{
    "costs": [
        {
            "jobRef": "J00GTH",
            "jobClientRef": "ABC23",
            "clientId": "3",
            "costTypeId": "23",
            "description": "desc",
            "supplierId": "34",
            "resourceId": "21",
            "unit": "1",
            "postingType": "1",
            "quantity": "3",
            "date": "12/12/2012",
            "inputDate": "12/12/2012",
            "taxType": "1",
            "unitCost": "23.45",
            "unitSalesCost": "45.54"
        }
    ]
}

XML payload example

<?xml version="1.0" encoding="UTF-8"?>
<costs>
    <jobRef>J00GTH</jobRef>
    <jobClientRef>abc123</jobClientRef>
    <clientId>32</clientId>
    <costTypeId>23</costTypeId>
    <description>a description</description>
    <supplierId>34</supplierId>
    <resourceId>21</resourceId>
    <unit>1</unit>
    <postingType>1</postingType>
    <quantity>3</quantity>
    <date>12/12/2012</date>
    <inputDate>12/12/2012</inputDate>
    <taxType>1</taxType>
    <unitCost>12.34</unitCost>
    <unitSalesCost>23.22</unitSalesCost>
</costs>

Available Response Representations

HTTP Code	Description	Schema
200	Cost(s) Posted	"result": "success"
400	Bad Request	Error
401	Unauthorized	Error
403	Forbidden	Error
404	Address Not Found	Error
405	Method Not Allowed	Error
500	Internal Server Error	Error

Example Success Response

{
    "result": "success",
    "result_msg": ""
}

Troubleshooting

401 Unauthorized

Response

401 Unauthorized

Reason

This error occurs if the OS-REST-AUTH-TOKEN has not been provided, has expired, or does not exist in the system

Resolution

Verify your OS-REST-AUTH-TOKEN with support

403 Forbidden

Response

403 Forbidden

Reason

This error indicates that something is blocking your connection to the server

Resolution

Open a ticket with the support team with details of your connection so that your access can be verified

404 Not Found

Response

404 Not Found

Reason

This error should only occur if the endpoint has been mistyped in some way, which will lead the call to an endpoint that does not exist

Resolution

Verify the endpoint matches the value specified in this article

405 Method Not Allowed

Response

405 Method Not Allowed

Reason

This error will occur if an unacceptable method has been used in the call such as GET or DELETE

Resolution

Ensure that you are using a POST call to this endpoint

Missing Mandatory Field

Response

{
    "result": "fail",
    "result_msg": "Missing mandatory field"
}

Reason

This error occurs if a mandatory field has been missed out of the call

Resolution

Ensure that your call follows the file spec above