Skip to content

Aimsio API (1.0.0)

Introduction

Aimsio provides a set of API endpoints and supported actions to facilitate communication with external software platforms / ERPs.

Each Aimsio account can access two server options: sandbox and portal

  • sandbox is the test environment we used to implement and test configuration changes for an account before live deployment.

  • portal is the live environment where accounts store their live transactions

Authentication

Our API utilizes basic username and password authentication to access the API.

If you already have an Admin username set up for your account inside Aimsio, this can be used for API authentication. However, the best practice would be to set up a separate user for integration purposes and keep this set of credentials private only to the developer.

Aimsio users also require specific permissions to access our API. Please contact our support/integration team so they can enable the required permissions.

Throughput limitation

We currently limit API calls after calls exceed more than 10 calls per second. If our API receives too many requests (ie: if the queue takes longer than 5 seconds to return the call), the request will timeout.

Up to 10 parallel calls are permitted. We do not limit the number of sequential calls. If your organization requires more headroom to complete calls to our API, please get in touch with us.

Usage - Querying data

For most entities with GET requests supported, there are two endpoints we supported:

  • GET all objects of that type

  • GET one speficic object based on its unique identifier (GUID/Id)

When you send a GET all request, the system will return an JSON array, and each JSON contains the following properties:

  • dtype: The object type

  • guid/id: Unique identifier of the object, generated by the Aimsio system

  • updatedAt: Object's last update timestamp in epoch millseconds

Using the returned Guid or ID, you can then query each specific object from the GET single request.

Usage - Posting data

To upload data, please review the object properties and example requests for each POST endpoint.

For our Master Data endpoints, you can create/edit new entries into Aimsio system.

For some other endpoints like Invoice or Timecard, we don't allow POSTing new entries, but updating status of existing entries are supported.

Object types like NRBs or Crew/Equipment records are included in the JobOrder GET response, but have to be POSTed through their own endpoints.

  • Crew records: Employee endpoint

  • Equipment records: Equipment endpoint

  • NRB records: NRB endpoint

Download OpenAPI description
aimsio_api.json
aimsio_api.yaml
Languages
Servers
Mock server

https://api.aimsio.com/_mock/aimsio_api/

Sandbox

https://sandbox.aimsio.com/

Production

https://portal.aimsio.com/

Master Data

Operations

Job Orders

Operations

Transactions

Operations

Non-recurring Billable Items

Request

Security
basicAuth
Bodyapplication/json
nrbListArray of objects(NonrecurringBillableItem)
curl -i -X POST \
  -u <username>:<password> \
  https://api.aimsio.com/_mock/aimsio_api/rest/api/standard/v1/NRB \
  -H 'Content-Type: application/json' \
  -d '{
    "nrbList": [
      {
        "nrbOriginReference": "AP-INV-123",
        "nrbJobOrderNumber": "JOB20250514",
        "nrbWBSSharedIdentifier": "JOB20250514-01.01",
        "nrbTypeName": "Other",
        "nrbAccountType": "Billable",
        "nrbIsBillable": true,
        "nrbVendorCode": "BIT",
        "nrbInvoiceNumber": "AP-INV-123",
        "nrbInvoiceDate": 1743528967000,
        "nrbPONumber": "PO-13624",
        "nrbIsExported": false,
        "isInternal": false,
        "nrbQuantity": 1,
        "nrbRate": 750,
        "nrbUpcharge": 10,
        "nrbVendorTax": "37.5",
        "nrbMarkupAppliesOn": "SUB_TOTAL",
        "nrbNotes": "Purchased field software"
      }
    ]
  }'

Responses

Bodyapplication/json
dtypestring
Default "IntegrationImportResult"
idinteger
guidstring
importConfigurationstring
numberOfEntitiesCreatedinteger
numberOfEntitiesEditedinteger
numberOfEntitiesEditedWithErrorsinteger
numberOfEntitiesNotImportedDueToErrorsinteger
extrastring
noticesArray of objects
updatedAtinteger
importResultTypestring
numberOfEntitiesImportedinteger
Response
application/json
{
  "dtype": "IntegrationImportResult",
  "id": 0,
  "guid": "4b3f8eef-4307-4068-ba88-9ef491945122",
  "importConfiguration": null,
  "numberOfEntitiesCreated": 0,
  "numberOfEntitiesEdited": 1,
  "numberOfEntitiesEditedWithErrors": 0,
  "numberOfEntitiesNotImportedDueToErrors": 0,
  "extra": null,
  "notices": [],
  "updatedAt": 1746815305412,
  "importResultType": null,
  "numberOfEntitiesImported": 1
}

All Non-recurring Billable Items

Request

curl -i -X GET \
  https://api.aimsio.com/_mock/aimsio_api/rest/api/standard/v1/NonRecurringBillableItem

Responses

OK

Bodyapplication/json
object
Response
application/json
{
  "value": [
    { … },
    { … },
    { … },
    { … },
    { … }
  ]
}

Non-recurring Billable Item

Request

Security
basicAuth
Path
nrbGuidstringrequired
curl -i -X GET \
  -u <username>:<password> \
  'https://api.aimsio.com/_mock/aimsio_api/rest/api/standard/v1/NonRecurringBillableItem/{nrbGuid}'

Responses

Shared Response

Bodyapplication/json
nrbGuidstring

Unique identifier and is automatically generated by Aimsio system. This is only used to update existing object

nrbExternalIdstringrequired

Recommended property to uniquely identify a new or existing object.

nrbOriginReferencestring

This property can be used to uniquely identify a new or existing object.

nrbJobOrderNumberstringrequired

Must be an existing job number

nrbWBSGuidstringread-only
nrbWBSSharedIdentifierstring

If provided, must be a valid WBS shared identifier under the NRB's job

nrbPONumberstring
nrbPurchaseOrderGuidstringread-only
nrbPurchaseOrderCostItemOriginReferencestringread-only
nrbInvoiceNumberstring
nrbInvoiceDateinteger

Timestamp in epoch millseconds

nrbNamestringrequired
nrbTypeUnamestring

For new objects, either nrbTypeUname or nrbTypeName is required

nrbTypeNamestringrequired

For new objects, either nrbTypeUname or nrbTypeName is required

nrbDocumentTypestring
Enum"RECEIPT_AP_INVOICE""RECEIPT_PACKING_SLIP""RECEIPT_FIELD_TICKET""RECEIPT_BOL"
nrbAccountTypestringrequired
Enum"Billable""Not Billable"
nrbIsBillablebooleanrequired
nrbVendorGuidstringread-only
nrbVendorCodestringrequired

Must be a valid existing company code that doesn't belong to "Client" type

nrbRatenumberrequired
nrbQuantitynumberrequired
nrbVendorTaxnumber
nrbUpchargenumber
nrbMarkupAppliesOnstring
Enum"SUB_TOTAL""SUB_TOTAL_AND_VENDOR_TAX"
nrbTotalAfterMarkupnumberread-only

Calculated by the system. nrbRate x nrbQuantity (+ nrbVendorTax if markup applies to vendor tax) x nrbUpcharge

nrbIsExportedboolean
isInternalboolean
nrbShouldReconcileWithPOboolean

If this flag is set to true, nrbExternalId and nrbPONumber are required

nrbBilledInGuidstringread-only
nrbBilledInNamestringread-only
nrbFileNamestring
nrbNotesstring
nrbCreatedAtintegerread-only

Timestamp in epoch milliseconds

nrbCreatedByUserNamestringread-only
nrbCreatedByFullNamestringread-only
nrbUpdatedAtintegerread-only

Timestamp in epoch milliseconds

nrbLineItemsArray of objectsread-only
nrbParentGuidstringread-only

The parent NRB guid if this is a child NRB

nrbParentExternalIdstringread-only

The parent NRB external ID if this is a child NRB

nrbChildrenArray of NonrecurringBillableItem

Children NRB items. Only appicable if nrbDocumentType = RECEIPT_AP_INVOICE. Children nrbDocumentType must not be RECEIPT_AP_INVOICE

Response
application/json
{
  "nrbFileName": "pdf_sample.pdf",
  "nrbExternalId": null,
  "nrbAccountType": "Billable",
  "nrbCreatedByFullName": "Admin Ken",
  "nrbIsBillable": true,
  "nrbQuantity": "1.000",
  "nrbTypeUname": "other_nrb_type",
  "nrbOriginReference": "AP-INV-123",
  "nrbLineItems": [
    { … }
  ],
  "nrbBilledInName": null,
  "nrbMarkupAppliesOn": "SUB_TOTAL",
  "nrbVendorGuid": "d74e8cbb-c7ce-43d9-be2d-c65f0ce0af49",
  "nrbWBSGuid": "b0dd1584-c59a-4a10-a64e-638177a54edc",
  "nrbInvoiceDate": 1743503400000,
  "nrbName": null,
  "nrbCreatedByUserName": "admin@kentest-sandbox",
  "nrbVendorTax": "37.500",
  "nrbPurchaseOrderGuid": null,
  "nrbPurchaseOrderCostItemOriginReference": null,
  "nrbPONumber": "PO-13624",
  "nrbGuid": "3f06d188-45ee-4ee0-83c3-85445748b649",
  "nrbUpcharge": "10.000",
  "nrbTotalAfterMarkup": "862.50",
  "nrbNotes": "Purchased field software",
  "nrbRate": "750.000",
  "nrbTypeName": "Other",
  "nrbCreatedAt": 1747849689000,
  "nrbUpdatedAt": 1747851986000,
  "nrbInvoiceNumber": "AP-INV-123",
  "nrbIsExported": false,
  "nrbBilledInGuid": null,
  "isInternal": false,
  "nrbVendorCode": "BIT"
}

Users

Operations