addCost API

Avatar
Ciarán Ainsworth
  • Updated
Follow

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