Ascendr's API empowers users to seamlessly integrate with the platform, facilitating efficient management of contacts and companies. The API supports operations such as creating, updating, retrieving, and deleting records, thereby streamlining data handling processes. To maintain optimal performance and ensure fair usage, the API enforces rate limits of 500 requests per minute and 30,000 requests per hour. This documentation provides comprehensive guidance on generating access tokens, utilising various endpoints, and adhering to best practices for effective API usage.

1. Generate a New Access Token

You can manually generate a new access_token through the admin portal.

Login to the Admin Portal:

Navigate to My Settings:

Once logged in, click on your user profile or settings icon.
Select "My Settings" from the dropdown menu.

Go to the API Token Section:

In the My Settings page, find and click on the "API TOKEN" section.

Generate a New Token:

In the API TOKEN section, click the "Generate Token" button.
A new access_token will be generated, and you will be able to copy it.

2. Base URL

All API requests to Ascendr should be directed to the following base URL:

https://app.ascendr.co.uk

Use this base URL to structure all your API calls, appending the relevant endpoints as needed.

3. Alternative Way to Generate a New Access Token & Refresh Token

The Login API authenticates the user and provides an access_token and refresh_token for use in subsequent requests.

URL: /login?loginType=hubspotapp

Credentials

{
  "username": "[email protected]",
  "password": "your_password"
}

Upon successful login, the user will be redirected with the access_token and refresh_token as query parameters.

http://hubspotapppath/login?access_token=<access_token>&refresh_token=<refresh_token>

4. Refresh Token API

The Refresh Token API allows the client to obtain a new access_token using the refresh_token

URL: /api/v1/token

Method: POST

Request Body (JSON):

{
    "grant_type": "refresh_token",
    "refresh_token": “your_refresh_token"
}

Headers:

- Authorization: Bearer {access_token}

Response:

Success (200 OK):

{
    "access_token": "new_access_token",
    "refresh_token": "new_refresh_token",
    "token_type": "Bearer",
    "expires_in": 25200
}

5. Create a new contact.

URL: /api/v1/contacts

Method: POST

Headers:

- Content-Type: application/json

- Authorization: Bearer {access_token}

Request Body (JSON):

{
  "firstName": "John Doe",
  "lastName": "John Doe",
  "email": "[email protected]",
  "telephone": "+1234567890",
  "add1": "123",
  "add2": "Main St",
  "add3": "Near",
 "city": "City",
 "country": "Country"
}

Response:

Success (200 Created):

{
  "id": 123,
  "status": true,
  "message": ”Contact created successfully”
}

Error (400 Bad Request):

{
  "status": false,
  "error": "Invalid JSON"
}

6. Retrieve a contact by ID.

URL: /api/v1/contacts/{contactId}

Method: GET

Headers:

- Authorization: Bearer {access_token}

Path Parameters:

- contactId (integer, required): The ID of the contact.

Response:

Success (200 OK):

{
    "status": true,
    "data": [
        {
            "id": "24",
            "userId": "24",
            "companyId": "0",
            "firstname": "Mahak",
            "lastname": "New",
            "isSuperUser": "0",
            "position": "",
            "email": "[email protected]",
            "telephone": "1234567890",
            "telephone2": "",
            "telephone3": "",
            "add1": "one",
            "add2": "two",
            "add3": "three",
            "city": "Panchkula",
            "postcode": "",
            "country": "India",
            "initials": "",
            "concatField": "Mahak New [email protected]",
            "colour": "",
            "icon": "",
            "hasPortalAccess": "1",
            "dtmAdded": "2022-10-17 04:33:02",
            "isDeleted": "0",
            "dtmDeleted": "2022-10-17 04:33:02",
            "deletedBy": "0",
            "dtmLastLogin": "0000-00-00 00:00:00",
            "platformType": "2",
            "dtmUpdated": "2024-09-19 11:32:00",
            "updatedBy": "258",
            "usersId": "24",
            "typeId": "0",
            "parentId": "0",
            "accountNumber": " ",
            "companyName": " ",
            "projectId": "7",
            "organization": "0",
            "department": "",
            "role": "",
            "timezone": "Etc/Greenwich",
            "telephoneType": "Mobile",
            "telephoneType2": "Mobile",
            "telephoneType3": " ",
            "permissions": "view-home,view-progress,view-week-view,view-deliverables,view-tasks,comment-on-tasks,change-task-status,complete-tasks,view-files,delete-files,view-contacts,add-contacts"
        }
    ]
}

Error (404 Not Found):

{
  "status": false,
  "error": "Contact not found"
}

7. Update an existing contact.

URL: /api/v1/contacts/{contactId}

Method: PUT

Headers:

- Content-Type: application/json

- Authorization: Bearer {access_token}

Path Parameters:

- contactId (integer, required): The ID of the contact.

Request Body (JSON):

{
  "firstName": "John Doe",
  "lastName": "John Doe",
  "email": "[email protected]",
  "telephone": "+1234567890",
  "add1": "123",
  "add2": "Main St",
  "add3": "Near",
 "city": "City",
 "country": "Country"
}

Response:

Success (200 OK):

{
  "id": 123,
  "status": true,
  "message": ”Contact updated successfully”
}

Error (400 Bad Request):

{
  "status": "error",
  "message": "Invalid JSON"
}

Error (404 Not Found):

{
  "status": false,
  "error": "Contact not found"
}

8. Delete a contact by ID.

Delete a contact by ID.

URL: /api/v1/contacts/{contactId}

Method: DELETE

Headers:

- Authorization: Bearer {access_token}

Path Parameters:

- contactId (integer, required): The ID of the contact.

Response:

Success (200 OK):

{
  "status": true,
  "message": "Contact deleted successfully"
}

Error (404 Not Found):

{
  "status": "error",
  "message": "Contact not found or could not be deleted"
}

9. Retrieve all contacts.

URL: /api/v1/contacts

Method: GET

Headers:

- Authorization: Bearer {access_token}

Response:

Success (200 OK):

{
    "status": true,
    "page": 1,
    "limit": 50,
    "total": 88,
    "data": [
        {...},
       {...}
            ]

}

10. Retrieve all contacts count.

URL: /api/v1/contacts/count

Method: GET

Headers:

- Authorization: Bearer {access_token}

Response:

Success (200 OK):

{
    "status": true,
    "data": {
        "count": 88
    }
}

11. Retrieve properties of contacts.

URL: /api/v1/contacts/properties

Method: GET

Headers:

- Authorization: Bearer {access_token}

Response:

Success (200 OK):

{
    "status": true,
    "data": {
        "user_records": [
            "id",
            "userId",
            "companyId",
            "firstname",
            "lastname",
            "isSuperUser",
            "position",
            "email",
            "telephone",
            "telephone2",
            "telephone3",
            "add1",
            "add2",
            "add3",
            "city",
            "postcode",
            "country",
            "initials",
            "concatField",
            "colour",
            "icon",
            "hasPortalAccess",
            "dtmAdded",
            "isDeleted",
            "dtmDeleted",
            "deletedBy",
            "dtmLastLogin",
            "platformType",
            "dtmUpdated",
            "updatedBy"
        ],
        "users_details": [
            "id",
            "usersId",
            "typeId",
            "parentId",
            "accountNumber",
            "companyName",
            "projectId",
            "organization",
            "department",
            "position",
            "role",
            "timezone",
            "telephoneType",
            "telephoneType2",
            "telephoneType3",
            "hasPortalAccess",
            "permissions"
        ]
    }
}

12. Search contacts.

URL: /api/v1/contacts/search

Method: GET

Headers:

- Authorization: Bearer {access_token}

Query Parameters:

You can filter contacts using one or more of the following parameters:

name (string): Filter by contact name.
email (string): Filter by email address.
telephone (string): Filter by phone number.
address (string): Filter by address.
city (string): Filter by city.
country (string): Filter by country.
companyName (string): Filter by associated company name.
organization (string): Filter by organization.
position (string): Filter by position within the company.
createdDate (date): Filter by the contact creation date.
modifiedDate (date): Filter by the last modified date.
deletedDate (date): Filter by the date when the contact was marked as deleted.

Response:

Success (200 OK):

{
    "status": true,
    "page": 1,
    "limit": 50,
    "total": 88,
    "data": [
        {...},
       {...}
            ]
}

13. Create a new company.

URL: /api/v1/companies

Method: POST

Headers:

- Content-Type: application/json

- Authorization: Bearer {access_token}

Request Body (JSON):

{
   "companyName": "TeQ Square",
    "email": "",
    "add1": "one",
    "add2": "two",
    "add3": "three",
    "city": "Birmingham",
    "country": "UK",
    "telephone": "1234567890"
}

Response:

Success (200 Created):

{
  "id": 123,
  "status": true,
  "message": ”Company created successfully”
}

Error (400 Bad Request):

{
  "status": false,
  "error": "Invalid JSON"
}

14. Retrieve a company by ID.

URL: /api/v1/companies/{companyId}

Method: GET

Headers:

- Authorization: Bearer {access_token}

Path Parameters:

- companyId (integer, required): The ID of the company.

Response:

Success (200 OK):

{
    "status": true,
    "company": [
        {
            "id": "62",
            "typeId": "1",
            "parentId": "0",
            "accountNumber": "COMP001",
            "companyName": "Company001",
            "abbreviation": "",
            "colour": "#D50000",
            "add1": "",
            "add2": "",
            "add3": "",
            "city": "",
            "postcode": "",
            "country": "",
            "email": "",
            "telephone": "",
            "projects": "0",
            "concatField": "COMP001 Company001        ",
            "dtmAdded": "2024-08-26 12:43:37",
            "addedBy": "0",
            "dtmUpdated": null,
            "updatedBy": null,
            "isDeleted": "0",
            "dtmDeleted": null,
            "deletedBy": "0",
            "companyId": "62",
            "companyType": "0",
            "commercialOwner": "0",
            "customerSuccessManager": "0",
            "supportModel": "0",
            "companyTier": "0",
            "verticals": null,
            "contractStartDate": null,
            "contractEndDate": null,
            "arr": "0",
            "currency": null,
            "executionAllowancePerYear": "0",
            "executionExceeded": "0",
            "activeUserAllowance": "0",
            "exceededAllowanceCommunicated": "0",
            "status": "0",
            "platformUsageTrendThisMonth": null,
            "platformUsageTrendLastMonth": null,
            "platformUsageTrendTwoMonthsAgo": null,
            "riskIndicators": null,
            "csmRagStatus": "0",
            "csmRiskComment": null,
            "commercialOwnerRagStatus": "0",
            "commercialOwnerRiskComment": null,
            "customerLifecycle": "0"
        }
    ]
}

Error (404 Not Found):

{
  "status": false,
  "error": "Company not found"
}

15. Update an existing company.

URL: /api/v1/companies/{companyId}

Method: PUT

Headers:

- Content-Type: application/json

- Authorization: Bearer {access_token}

Path Parameters:

- companyId (integer, required): The ID of the company.

Request Body (JSON):

{
    "companyName": "TeQ Square",
    "email": "",
    "add1": "one",
    "add2": "two",
    "add3": "three",
    "city": "Birmingham",
    "country": "UK",
    "telephone": "1234567890"
}

Response:

Success (200 OK):

{
  "id": 123,
  "status": true,
  "message": ”Company updated successfully”
}

Error (400 Bad Request):

{
  "status": "error",
  "message": "Invalid JSON"
}

Error (404 Not Found):

{
  "status": false,
  "error": "Company not found"
}

16. Delete a company by ID.

URL: /api/v1/companies/{companyId}

Method: DELETE

Headers:

- Authorization: Bearer {access_token}

Path Parameters:

- companyId (integer, required): The ID of the company.

Response:

Success (200 OK):

{
  "status": true,
  "message": "Company deleted successfully"
}

Error (404 Not Found):

{
  "status": "error",
  "message": "Company not found or could not be deleted"
}

17. Retrieve all companies.

URL: /api/v1/companies

Method: GET

Headers:

- Authorization: Bearer {access_token}

Response:

Success (200 OK):

{
    "status": true,
    "page": 1,
    "limit": 50,
    "total": 88,
    "data": [
        {...},
       {...}
            ]
}

18. Retrieve all companies count.

URL: /api/v1/companies/count

Method: GET

Headers:

- Authorization: Bearer {access_token}

Response:

Success (200 OK):

{
    "status": true,
    "data": {
        "count": 88
    }
}

19. Retrieve properties of companies.

URL: /api/v1/companies/properties

Method: GET

Headers:

- Authorization: Bearer {access_token}

Response:

Success (200 OK):

{
    "status": true,
    "data": {
        "companies": [
            "abbreviation",
            "accountNumber",
            "add1",
            "add2",
            "add3",
            "addedBy",
            "city",
            "colour",
            "companyName",
            "concatField",
            "country",
            "deletedBy",
            "dtmAdded",
            "dtmDeleted",
            "dtmUpdated",
            "email",
            "id",
            "isDeleted",
            "parentId",
            "postcode",
            "projects",
            "telephone",
            "typeId",
            "updatedBy"
        ],
        "companies_details": [
            "activeUserAllowance",
            "addedBy",
            "arr",
            "commercialOwner",
            "commercialOwnerRagStatus",
            "commercialOwnerRiskComment",
            "companyId",
            "companyTier",
            "companyType",
            "contractEndDate",
            "contractStartDate",
            "csmRagStatus",
            "csmRiskComment",
            "currency",
            "customerLifecycle",
            "customerSuccessManager",
            "deletedBy",
            "dtmAdded",
            "dtmDeleted",
            "dtmUpdated",
            "exceededAllowanceCommunicated",
            "executionAllowancePerYear",
            "executionExceeded",
            "id",
            "isDeleted",
            "platformUsageTrendLastMonth",
            "platformUsageTrendThisMonth",
            "platformUsageTrendTwoMonthsAgo",
            "riskIndicators",
            "status",
            "supportModel",
            "updatedBy",
            "verticals"
        ]
    }
}

20. Search companies.

URL: /api/v1/companies/search

Method: GET

Headers:

- Authorization: Bearer {access_token}

Query Parameters:

You can filter companies using one or more of the following parameters:

companyName (string): Filter by company name.
email (string): Filter by email address.
telephone (string): Filter by phone number.
address (string): Filter by address.
city (string): Filter by city.
country (string): Filter by country.
createdDate (date): Filter by the company creation date.
modifiedDate (date): Filter by the last modified date.
deletedDate (date): Filter by the date when the company was marked as deleted.

Response:

Success (200 OK):

{
    "status": true,
    "page": 1,
    "limit": 50,
    "total": 88,
    "data": [
        {...},
       {...}
            ]
}