Limitations

Must have access to Penta APIs. Please contact Penta's account management in order to obtain a client and secret.
Compatible with PENTA version 24.1 and up.

Authorization

PentaConnect uses an Oauth2 framework for authorization.  All requests to PentaConnect APIs require an access token obtained from Penta’s Oauth2 server to be supplied as a request header.
See PentaConnect Authorization for details.

Versioning

v1/v2/etc of any API requires version 24.01 or higher of the underlying PentaConnect Service.

All other versions require the corresponding version of the underlying PentaConnect Service. These versions will be deprecated in the future and replaced with v1+.

Tiers

PentaConnect has 3 pre-defined Tiers of service:

Tier 1: Up to 50,000 API calls per 24 hours

Tier 2: Up to 20,000 API calls per 24 hours

Tier 3: Up to 15,000 API calls per 24 hours

Unless specified otherwise in the API Claims for the environment, Tier 3 is the default setting for the call rate quota, which is specified in the Azure APIM Policy.

Each distinct API can have it’s own plan tier (PentaConnectAPPlanTier, PentaConnectProjectManagementPlanTier, etc)

Once the call volume has been reached, the caller will receive a 403 Forbidden response. In addition, the response will include a “Retry-After” header whose value is the recommended retry interval in seconds.

Rate Limit

In addition, PentaConnect also has a built-in rate limit of 100 calls per 10 seconds, which is specified in the Azure APIM Policy. This is to prevent API usage spikes.

Once the rate limit has been reached, the caller will receive a 429 Too Many Requests response.

Timeouts

Requests time out after 300 seconds (Azure APIM limit), but may drop earlier depending on underlying network infrastructure.

Common Query Parameters

Most PentaConnect GET endpoints make the following request parameters available for restricting the data returned in the response.  If calls are not limiting to specific data using the other endpoint-specific request parameters, it is recommended that one or more of these parameters be specified to avoid unworkably large responses.
PageSize - The request can return records one page at a time rather than the entire record set. This is the number of records to return on each page. It is not required in the request, but is the only request parameter needed to activate paging.
PageIndex - When paging is activated, this value indicates which page of records should be returned. (Zero-based - use 0 for the first page, 1 for the second, etc). Default is 0 if unspecified.
Together, these parameters can be used to return data a page at a time.  For example, if you specify PageSize of 100 and PageIndex of 5, the GET will return records 501 through 600 of the overall result set.
ModifiedSince - This allows you to only retrieve data that has been modified in Penta since a particular date/time. 
Examples: ModifiedSince=2024-01-01 or ModifiedSince=2023-08-08T12:40:00-05:00
SearchText - This allows you to limit to records where key data elements match a specified string.  Refer to individual endpoints' documentation for lists of the values that are compared to the search string.

Common Request Response Codes

200

Success. This response code occurs when a request has completed successfully.

The following is a sample response from a GET request:

{
    "HoldReasons": [
        {
            "HoldCode": "100",
            "Description": "100",
            "ManualInsert": false
        }
    ],
    "PageIndex": 0,
    "TotalSize": 1,
    "HasMoreData": false,
    "Success": true,
    "ResponseProcessStatus": "Success"
}

The following are both examples of a response from a POST request. In the first example, the data was successfully posted to PENTA, and the data is returned for confirmation by the user. In the second example, the request was processed successfully, but a validation check failed. The user is presented with the error message(s).

Example 1:

{
    "InterfaceRequestId": "CC00000000110",
    "InterfaceRequestType": "CC",
    "Costcodes": [
        {
            "JobId": "100",
            "JobName": "MILWAUKEE",
            "CostType": "B",
            "CostTypeDescription": "Burden",
            "Costcode": "8998",
            "UnitOfMeasure": "FT",
            "Status": "Active",
            "ModificationDate": "2024-03-18T14:46:02",
            "Description": "Test from API",
            "EstimatedHours": 0,
            "EstimatedQuantity": 1.2,
            "PurchaseOrderRequiredForAPCharges": false,
            "SystemAssignedKey": 145538,
            "UserDefinedFieldsRowId": 7041919,
            "EstimatedCost": 323,
            "StatusDate": "2024-03-18T00:00:00",
            "UserDefinedFields": []
        }
    ],
    "Status": "CompletedSuccessfully",
    "Messages": [],
    "Success": true,
    "ResponseProcessStatus": "Success"
}

Example 2:

{
    "InterfaceRequestId": "CC00000000111",
    "InterfaceRequestType": "CC",
    "Costcodes": [],
    "Status": "Rejected",
    "Messages": [
        "ERROR: Job 1002893 is not valid."
    ],
    "Success": true,
    "ResponseProcessStatus": "Success"
}

400

One reason that this response code can occur could be because data which is fundamental to the request is missing or invalid. In that scenario, the response returned from the service is formatted differently than what the user might expect. The following are two examples:

Example 1:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-d9e18660b836ba6a8a62bdca735fe650-9c567edc17ce535e-00",
  "errors": {
    "Costcodes[0].Costcode": [
      "The Costcode field is required."
    ]
  }
}

Example 2:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-4dc58a3f35c7291e8e88f7660ee84eb7-146285eaa99bed2b-00",
  "errors": {
    "Costcodes[0].Units": [
      "Units cannot contain more than 3 decimal places or be longer than 12 digits"
    ]
  }
}