ATS External Integration Guide

Please follow the link to view the complete data schema of ATS.

The external system can get the object by using the salesforce standard API.

Endpoint:

https://<your-instance>.salesforce.com/services/data/vXX.0/sobjects/<your-object-api-name>/describe

Note:

Before accessing objects through the API, make sure the external system is properly authenticated with your Salesforce org.

• v59.0 = Spring '24 release
• v60.0 = Summer '24 release
• v61.0 = Winter '25 release

• Access the latest features and field types
• Avoid deprecated functionality
• Improve compatibility with newer Salesforce objects or APIs

Base URL:

https://<your-instance>.salesforce.com/services/data/vXX.0/sobjects/<your-object-api-name>/describe

• Replace with your Salesforce domain.
• Replace vXX.0 with your Salesforce API version (e.g., v60.0 for Spring '24).

HTTP method: POST

Token Request Endpoint:

https://login.salesforce.com/services/oauth2/token

Required Parameters

Example Request:

https://login.salesforce.com/services/oauth2/token?grant_type=password&client_id=YOUR_CLIENT_ID&client_secret=YOUR_C
LIENT_SECRET&username=YOUR_USERNAME&password=YOUR_PASSWORD_AND_SECURITY_TOKEN

Successful Response:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "instance_url": "https://yourInstance.salesforce.com",
  "id": "https://login.salesforce.com/id/ORG_ID/USER_ID",
  "token_type": "Bearer",
  "issued_at": "TIMESTAMP",
  "signature": "SIGNATURE" 
}

Request Parameters:

• Format: application/json
• Structure: JSON object
• Field Validation Rules:

Example: Successful POST Response (Create Record)

{
    "hasErrors": false,
    "results": [
        {
            "referenceId": "ref1",
            "id": "a0LEm000007fZDxMAM"
        },
        {
            "referenceId": "ref2",
            "id": "a0LEm000007fZDyMAM"
        }
    ]
}

Example: Successful GET Query Response

{
    "totalSize": 1,
    "done": true,
    "records": [
        {
            "attributes": {
                "type": "bpats__Job__c",
                "url": "/services/data/v57.0/sobjects/bpats__Job__c/a0MEm000004fFnBMAU"
            },
            "Name": "Salesforce Developer Test",
            "bpats__End_Date__c": null
        }
    ]
}

Example: 400 Bad Request

{
    "hasErrors": true,
    "results": [
        {
            "referenceId": "ref3",
            "errors": [
                {
                    "statusCode": "REQUIRED_FIELD_MISSING",
                    "message": "Required fields are missing: [LastName]",
                    "fields": [
                        "LastName"
                    ]
                }
            ]
        }
    ]
}

Possible causes:

• Your API request body is missing a required field (in this case, LastName).
• Validation rules on the Salesforce object require this field.

How to Handle:

• Before sending the request, ensure that all mandatory fields are populated.
• Implement client-side or server-side validation to check required fields before making the API call.

Example: 401 Unauthorized (Invalid Token)

[
  {
    "message": "Session expired or invalid",
    "errorCode": "INVALID_SESSION_ID" 
  }
]

Possible Causes:

• The session (OAuth token or session ID) is expired, revoked, or invalid.
• The user was logged out, or the token has timed out.

How to Handle:

• Reauthenticate and obtain a new access token/session ID.
• Implement automatic token refresh logic if using OAuth.
• Check your session timeout settings and ensure sessions are still valid before making requests.

Example: 400 Not Found

[
  {
    "message": "The requested resource does not exist",
    "errorCode": "NOT_FOUND"
  }
]

Possible Causes:

• You're trying to access a record, object, or endpoint that doesn't exist.
• You might have a typo in the URL or the record ID provided is wrong.
• The resource might have been deleted.

How to Handle:

• Verify that the URL is correct.
• Ensure the record or resource actually exists before requesting it.
• Implement error handling to gracefully show "resource not found" messages.

Example: 400 REQUIRED FIELD MISSING

{
    "hasErrors": true,
    "results": [
        {
            "referenceId": "ref3",
            "errors": [
                {
                    "statusCode": "REQUIRED_FIELD_MISSING",
                    "message": "Required fields are missing: [LastName]",
                    "fields": [
                        "LastName"
                    ]
                }
            ]
        }
    ]
}

Possible Causes:

• Your API request body is missing a required field (in this case, LastName).
• Validation rules on the Salesforce object require this field.

How to Handle:

• Before sending the request, ensure that all mandatory fields are populated.
• Implement client-side or server-side validation to check required fields before making the API call.

Example: 404 INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST

[
    {
        "message": "Status: bad value for restricted picklist field: Test",
        "errorCode": "INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST",
        "fields": [
            "bpats__Status__c"
        ]
    }
]

Possible Causes:

• You're trying to set a picklist field (bpats__Status__c) to a value (Test) that isn't allowed.
• The picklist is restricted, meaning only predefined values are accepted.

How to Handle:

• Fetch the allowed picklist values from Salesforce metadata or manually maintain a list.
• Validate picklist inputs before sending them to the server.
• Show users only valid choices in UI dropdowns.

Example: 400 STRING_TOO_LONG

{
  "hasErrors": true,
  "results": [
    {
      "referenceId": "ref3",
      "errors": [
        {
          "statusCode": "STRING_TOO_LONG",
          "message": "First Name: data value too large: candidate test candidate test candidate test 
          candidate test candidate test candidate test candidate test candidate test candidate test 
          candidate test candidate test candidate test candidate test candidate test candidate test 
          candidate test candidate test candidate test candidate test candidate test candidate test 
          candidate test candidate test candidate 
          test candidate test candidate (max length=40)",
          "fields": [
            "FirstName"
          ]
        }
      ]
    }
  ]
}

Possible Causes:

• The value you're trying to insert into the FirstName field exceeds the maximum allowed characters (40 characters in this case).

How to Handle:

• Limit field input length based on Salesforce field metadata (e.g., maxlength in input fields).
• Truncate or validate strings before sending the request.
• Show the user a clear message like "First Name must be 40 characters or fewer."

HTTP method: GET

• Endpoint:

  https://.salesforce.com/services/data/vXX.0/limits

• Replace vXX.X with the latest salesforce API version.

1. Pagination: The Salesforce REST API returns a maximum of 2,000 records per SOQL query response.


   If the query matches more than 2,000 records:


• Only the first 2,000 records are returned in the initial response.
• A nextRecordsUrl field is included to fetch the next batch.


Example usage for retrieving the remaining query results

Endpoint:

 https://<your-instance>.salesforce.com/services/data/v63.0/query/0r8xx49yn9SOnOmAAL-2000

Example response body

JavaScript

{
    "done" : true,
    "totalSize" : 3214,
    "records" : [...]
}

2. Filtering: Filtering is done using the WHERE clause in SOQL. You can filter based on field values using logical operators.

Operator	Description	Example
=	Equals	status = 'Interview'
!=	Not equal	status != 'Rejected'
> <	Greater than / less than	createdDate > 2024-01-01T00:00:00Z
IN	Within a set of values	status IN ('Open', 'Interview')
LIKE	Pattern matching (with %)	name LIKE 'John%'

Example:

https://<your-instance>.salesforce.com/services/data/v63.0/query/?q=SELECT+Name,+bpats__End_Date__c,+bpats__Status__c+FROM+bpats__Job__c+WHERE+bpats__Status__c=’Open’

This query filters only Jobs whose status is Open.


3. Sorting: Sorting is done using the ORDER BY clause.

Parameter	Description
ORDER BY	Field(s) to sort on
ASC	Ascending order (default)
DESC	Descending order

Example:

https://&lgt;your-instance>.salesforce.com/services/data/v63.0/query/?q=SELECT+Name,+bpats__End_Date__c+FROM+bpats__Job__c+ORDER+BY+CreatedDate+DESC

This returns the newest Job first.


4. Formatting:
1. Date and Time: Use the salesforce standard format


   Example: 2025-04-29T15:45:00Z

   When filtering by dates in SOQL, use this format:


https://.salesforce.com/services/data/v57.0/query/?q=SELECT+Name,+bpats__End_Date__c,+bpats__Status__c+FROM+bpats__Job__c+WHERE+CreatedDate<2025-01-01T00:00:00Z
Numeric Values
  Use plain numbers without any formatting (no commas, no currency symbols).
  ✅  10000
  ❌  10,000 or $10000
 Decimal numbers must use a dot (.) as the decimal separator.
  ✅  1234.56
Text String
  Enclose string values in single quotes when used in SOQL.

  Example: WHERE Name = 'John Doe'


Boolean Values
  Use lowercase true or false

  Example:
JavaScript

{
  "isActive": true
}

1. Asymbl ATS Job Portal Permission Set: This permission set is designed for external-facing portals.

   Object Access & Allowed Operations

Object	Read	Create	Edit	Delete	View All	Modify All
Job Board Application	✅	✅	❌	❌	❌	❌
Job	✅	❌	❌	❌	❌	❌



2. External Interview Feedback Permission Set: Permission set is designed to submit feedback from external site

   Object Access & Allowed Operations

Object	Read	Create	Edit	Delete	View All	Modify All
Interview Feedback	✅	✅	❌	❌	❌	❌
Interview Topic Feedback	✅	✅	❌	❌	❌	❌
Interview Topic	✅	✅	❌	❌	❌	❌
Interview	✅	✅	❌	❌	❌	❌
Interview Template Detail	✅	❌	❌	❌	❌	❌
Interview Template	✅	❌	❌	❌	❌	❌
Contact	✅	❌	❌	❌	❌	❌



3. Asymbl ATS User Permission Set: This permission set grants users access to nearly all object permissions within the system, including Read, Create, and Edit capabilities. However, users assigned to this permission set do not have Delete access to any objects.

   Object Access & Allowed Operations

Object	Read	Create	Edit	Delete	View All	Modify All
ATS Action Link	✅	❌	❌	❌	❌	❌
ATS Action	✅	❌	❌	❌	❌	❌
ATS Applicant	✅	✅	✅	❌	❌	❌
ATS List Filter	✅	✅	✅	❌	❌	❌
ATS Log	✅	✅	✅	❌	❌	❌
ATS Stage	✅	✅	✅	❌	❌	❌
ATS Template Filter	✅	✅	✅	❌	❌	❌
ATS Template Stage	✅	❌	❌	❌	❌	❌
ATS Template	✅	❌	❌	❌	❌	❌
ATS Timeline Child	✅	✅	✅	❌	❌	❌
ATS Timeline Configuration	✅	✅	✅	❌	❌	❌
Account	✅	✅	✅	❌	❌	❌
Branch	✅	✅	✅	❌	❌	❌
Contact	✅	✅	✅	❌	❌	❌
Contact List	✅	✅	✅	❌	❌	❌
Interview Feedback	✅	✅	✅	✅	✅	✅
Interview Template Detail	✅	❌	❌	❌	❌	❌
Interview Template	✅	❌	❌	❌	❌	❌
Interview Topic Feedback	✅	✅	✅	❌	❌	❌
Interview Topic	✅	✅	✅	❌	❌	❌
Interview	✅	✅	✅	❌	❌	❌
Job Board Application	✅	✅	✅	❌	❌	❌
Job	✅	✅	✅	❌	❌	❌
Offer	✅	✅	✅	❌	❌	❌
Placement Credit Template Entry	✅	✅	✅	❌	❌	❌
Placement Credit Template	✅	✅	✅	❌	❌	❌
Placement Credit	✅	✅	✅	❌	❌	❌
Placement	✅	✅	✅	❌	❌	❌
Purchase Order	✅	✅	✅	❌	❌	❌
Retained Milestone	✅	✅	✅	❌	❌	❌
Work Site Location	✅	✅	✅	❌	❌	❌



4. Asymbl ATS Admin Permission Set: This permission set provides full administrative access within the Asymbl ATS system. Users with this role have Read, Create, Edit, andand Delete permissions across all standard and custom objects

   Object Access & Allowed Operations

Object	Read	Create	Edit	Delete	View All	Modify All
ATS Action Link	✅	✅	✅	✅	✅	✅
ATS Action	✅	✅	✅	✅	✅	✅
ATS Applicant	✅	✅	✅	✅	✅	✅
ATS List Filter	✅	✅	✅	✅	✅	✅
ATS Log	✅	✅	✅	✅	✅	✅
ATS Stage	✅	✅	✅	✅	✅	✅
ATS Template Filter	✅	✅	✅	✅	✅	✅
ATS_Template Stage	✅	✅	✅	✅	✅	✅
ATS Template	✅	✅	✅	✅	✅	✅
ATS Timeline Child	✅	✅	✅	✅	✅	✅
ATS Timeline Configuration	✅	✅	✅	✅	✅	✅
Account	✅	✅	✅	✅	✅	✅
Branch	✅	✅	✅	✅	✅	✅
Contact	✅	✅	✅	✅	✅	✅
Contact List	✅	✅	✅	✅	✅	✅
Interview Feedback	✅	✅	✅	✅	✅	✅
Interview Template Detail	✅	✅	✅	✅	✅	✅
Interview Template	✅	✅	✅	✅	✅	✅
Interview Topic Feedback	✅	✅	✅	✅	✅	✅
Interview Topic	✅	✅	✅	✅	✅	✅
Interview	✅	✅	✅	✅	✅	✅
Job Board Application	✅	✅	✅	✅	✅	✅

Method: Connected App in Salesforce

Security Note:

Tip: