# Jobs

A job document represents a client's request for cargo inspection that can be assigned to an inspection company. It tracks all related information to jobs, including its type, status, location, cargo and instructions for the inspector.

# Data Model

Field Type Description
workspace reference ​ ID of this job's workspace
parent reference ​ ID of job's parent document. Usually empty
xref string ​ Job external id to reference client's internal systems
refNumber string Job reference number for use in client-vendor communication and paperwork
tripNumber string Vessel trip number
status string Status of the job. Possible values: pending, active, complete, cancelled
activity string Possible values are: load, discharge, sts, transfer, sample
eta datetime ​ Estimated time of arrival at port
etc datetime ​ Estimated date of job completion
notes text ​ Comments, notes, additional instructions
location Catalog reference Inspection location
transports Array<Catalog reference> List of vessels being inspected
cargo.product Catalog reference Product being inspected
cargo.quantity float Product quantity
cargo.uom Catalog reference Unit of measure
requested.quality boolean true if quality results are expected from this inspection job
requested.quantity boolean true if quantity results are expected from this inspection job
requested.timelog boolean true if timelog is expected from this inspection job
vendor Catalog reference ​ Cargo shipper
client Catalog reference Inspection company

# API

# List all jobs

Returns a list of all jobs in the workspace specified. Optional query parameters can be used for paginating and sorting.

GET /workspaces/{workspace_id}/jobs

# URL parameters

Parameter Description Format
workspace_id Integration workspace id reference

# Query parameters

​ Parameter Description Format Default
limit Maximum number of records to return integer
offset The number of records to skip integer 0
sort List of comma-separated ordering criteria field:asc|desc
data model field Name of the field to search for. Any field from the data model can be used any

​ ​

# Create a job

Creates a new job and upon success returns that same data structure with a unique id field added that can be used to reference the job in subsequent requests.

POST /workspaces/{workspace_id}/jobs

# URL parameters

Parameter Description Format
workspace_id Integration workspace id reference

# Request body

See data model

# Request example:

hide code
{
    "xref": "45678",
    "refNumber": "FTF100500",
    "tripNumber": "TRIP123",
    "status": "active",
    "activity": "sample",
    "eta": "2019-06-28T14:00:00.000Z",
    "etc": "2019-06-30T17:00:00.000Z",
    "notes": "Ready for a patch test",
    "location": {
        "xref": "4567",
        "name": "Finnart"
    },
    "transports": [{
        "name": "Nameless Barge",
        "xref": "13579"
    }],
    "cargo": {
        "product": {
        "xref": "123",
        "name": "Baobab"
        },
        "quantity": 100500,
        "uom": {
            "xref": "2",
            "name": "Liter"
        }
    },
    "requested": {
        "quality": true,
        "quantity": true,
        "timelog": true
    },
    "vendor": "e2ee56c5-76a5-4b95-a723-b3c37c2111ab",
    "client": "a4e8781f-6d66-454e-86d4-45cb5a9202d2"
}

# Response example:

hide code
{
    "id": "96eb4e58-ca31-4086-8f68-78dcce7097b2",
    "body": {
        "xref": "5678",
        "refNumber": "FTF100500",
        "tripNumber": "TRIP123",
        "status": "active",
        "client": "a4e8781f-6d66-454e-86d4-45cb5a9202d2",
        "vendor": "e2ee56c5-76a5-4b95-a723-b3c37c2111ab",
        "activity": "sample",
        "eta": "2019-06-28T14:00:00.000Z",
        "etc": "2019-06-30T17:00:00.000Z",
        "notes": "Ready for a patch test",
        "location": "94cfbf6d-6a54-4a0c-8260-1071a13bea1b",
        "transports": [
            "cdcfbd0d-c7b7-4816-a4e8-fe2ea9b9a071"
        ],
        "cargo": {
            "product": "37a7cb1a-557f-451c-af60-608052776237",
            "quantity": 100500,
            "uom": "41ad68ef-51f9-4a00-bb72-f3153cbc876c"
        },
        "requested": {
            "quality": true,
            "quantity": true,
            "timelog": true
        }
    }
}

​ Creation of a job adds missing records to the catalogs. Mapped catalogs include: methods, locations, transports, products, uom, tests, timelogEvents.

# Get a specific job

Retrieves a single job specified by the unique ID for that job. This id field can be found in the response received when creating or listing jobs.

GET /workspaces/{workspace_id}id/jobs/{job_id}

# URL parameters

Parameter Description Format
workspace_id Integration workspace id reference
job_id Job id reference

# Response example:

hide code
{
    "xref": "5678",
    "refNumber": "FTF100500",
    "tripNumber": "TRIP123",
    "status": "active",
    "client": "a4e8781f-6d66-454e-86d4-45cb5a9202d2",
    "vendor": "e2ee56c5-76a5-4b95-a723-b3c37c2111ab",
    "activity": "sample",
    "eta": "2019-06-28T14:00:00.000Z",
    "etc": "2019-06-30T17:00:00.000Z",
    "notes": "Ready for a patch test",
    "location": "94cfbf6d-6a54-4a0c-8260-1071a13bea1b",
    "transports": [
        "cdcfbd0d-c7b7-4816-a4e8-fe2ea9b9a071"
    ],
    "cargo": {
        "product": "37a7cb1a-557f-451c-af60-608052776237",
        "quantity": 100500,
        "uom": "41ad68ef-51f9-4a00-bb72-f3153cbc876c"
    },
    "requested": {
        "quality": true,
        "quantity": true,
        "timelog": true
    }
}

# Update a job

Updates a job specified by the unique ID for that job. This id field can be found in the response received when creating or listing jobs.

PATCH /workspaces/{workspace_id}/jobs/{job_id}

# URL parameters

Parameter Description Format
workspace_id Integration workspace id reference
job_id Job id reference

# Request body

See data model

# Request example:

hide code
{
    "location": {
        "xref": "100500",
        "name": "Some Port"
    }
}

# Response example:

hide code
{
    "xref": "5678",
    "refNumber": "FTF100500",
    "tripNumber": "TRIP123",
    "status": "active",
    "client": "a4e8781f-6d66-454e-86d4-45cb5a9202d2",
    "vendor": "e2ee56c5-76a5-4b95-a723-b3c37c2111ab",
    "activity": "sample",
    "eta": "2019-06-28T14:00:00.000Z",
    "etc": "2019-06-30T17:00:00.000Z",
    "notes": "Ready for a patch test",
    "location": "2bf8d3d5-f492-4d75-9ba0-f97263d0796e",
    "transports": [
        "cdcfbd0d-c7b7-4816-a4e8-fe2ea9b9a071"
    ],
    "cargo": {
        "product": "37a7cb1a-557f-451c-af60-608052776237",
        "quantity": 100500,
        "uom": "41ad68ef-51f9-4a00-bb72-f3153cbc876c"
    },
    "requested": {
        "quality": true,
        "quantity": true,
        "timelog": true
    }
}

# Delete a job

Deletes a job specified by the unique ID for that job. If the job id does not exist, this call returns an error.

DELETE ​/workspaces/{workspace_id}/jobs/{job_id}

# URL parameters

Parameter Description Format
workspace_id Integration workspace id reference
job_id Job id reference

# Response example:

hide code
{
    "xref": "5678",
    "refNumber": "FTF100500",
    "tripNumber": "TRIP123",
    "status": "active",
    "client": "a4e8781f-6d66-454e-86d4-45cb5a9202d2",
    "vendor": "e2ee56c5-76a5-4b95-a723-b3c37c2111ab",
    "activity": "sample",
    "eta": "2019-06-28T14:00:00.000Z",
    "etc": "2019-06-30T17:00:00.000Z",
    "notes": "Ready for a patch test",
    "location": "2bf8d3d5-f492-4d75-9ba0-f97263d0796e",
    "transports": [
        "cdcfbd0d-c7b7-4816-a4e8-fe2ea9b9a071"
    ],
    "cargo": {
        "product": "37a7cb1a-557f-451c-af60-608052776237",
        "quantity": 100500,
        "uom": "41ad68ef-51f9-4a00-bb72-f3153cbc876c"
    },
    "requested": {
        "quality": true,
        "quantity": true,
        "timelog": true
    }
}
Last Updated: 8/24/2021, 7:59:53 PM