Developers
      Back to home
      1. MyFrankCrum Knowledge Base
      2. Developers

      MyFrankCrum Client API: Developer API Endpoint Guide

      Introduction
      Welcome to the MyFrankCrum Client API documentation. This API is designed to provide read-only access to high-level accounting and employee data within our system, enabling seamless integration with your applications for reporting and data analysis. This API and the developer portal are hosted on the Mulesoft platform to better protect access to secure data.

      Base URL
      The Base URL is the foundational part of the API endpoint that remains constant across all requests. It defines the root address to which all the specific endpoints are appended. In the MyFrankCrum Client API, the base URL provides access to the main system that holds the payroll and employee data.

      Example Base URL:

      https://clientapi.frankcrum.com/v1/clients/

      Purpose
      The base URL serves as the entry point for the API, directing your requests to the correct system. All specific API calls, such as retrieving project IDs or employee information, are appended to this base URL.

      Authentication
      Access to the API requires authentication via a client_id and client_secret. These credentials must be included in the headers of every API request to ensure secure communication.

      Authentication Headers:

      • client_id: Your unique client identifier.
      • client_secret: The secret key associated with your client ID.

      Example Headers:

      --header 'client_id: [your-client-id]' \
      --header 'client_secret: [your-client-secret]'

      Obtaining Credentials:
      Before you can connect to the API, you must be listed as an approved user by the client admin, register in the developer portal, and request application access which will generate your client_id and client_secret credentials. These credentials are essential for verifying your identity and granting access to the appropriate data.

      Once you have your authentication credentials, you will be able to retrieve high-level, read-only data about accounting activities, employee details, and other related information from our system.

      Please ensure that your authentication credentials are kept secure and are not exposed in publicly accessible areas, such as code repositories or logs.

      API Endpoints Overview

      Below is a list of the available endpoints in the MyFrankCrum Client API, along with a brief description of their purpose:

      1. Get All Project IDs Configured for the Client:
        ▪ Endpoint: /clients/projectID
        ▪ Purpose: Retrieves a list of all project IDs and company codes associated with the provided client_id and client_secret. This endpoint does not require any additional parameters.
      2. Get All Employees Under a Project ID:
        ▪ Endpoint: /clients/{projectID}/employees
        ▪ Purpose: Retrieves a list of all employees associated with a specific projectID. This endpoint allows you to gather basic employee information for the entire project.
      3. Get Employee Information Under a Project ID and Employee ID:
        ▪ Endpoint: /clients/{projectID}/employees/{employeeID}
        ▪ Purpose: Retrieves detailed information about a specific employee identified by employeeID under a given projectID. This allows for targeted access to individual employee records.
      4. Get Employee Information with Employment Detail:
        ▪ Endpoint: /clients/{projectID}/employees/{employeeID}/employment-detail
        ▪ Purpose: Retrieves comprehensive information about a specific employee, including detailed employment data. This endpoint is useful for accessing in-depth employment-related details.
      5. Get All Accounting Information Under a Project ID and Date:
        ▪ Endpoint: /clients/{projectID}/account-info/{dateIN}
        ▪ Purpose: Retrieves a list of accounting details associated with a specific projectID, filtered by the given date. This endpoint is useful for obtaining general ledger data within a company.

      API Endpoint: Retrieve Project IDs

      Endpoint:

      https://clientapi.frankcrum.com/v1/clients/projectID

      Headers:

      ▪ client_id: [client-id-here]
      ▪ client_secret: [client-secret-here]

      Path Parameters:

      ▪ NONE -

      Example cURL Request:

      curl --location 'https://clientapi.frankcrum.com/v1/clients/projectID' \
      --header 'client_id: [client-id-here]' \
      --header 'client_secret: [client-secret-here]'

      NOTE: URL is CASE-SENSITIVE.

      Example Response:

      {
      "projectId": "22016",
      "companyCode": [
      "200MR"
      ],
      "projectId": "32162",
      "companyCode": [
      "90023"
      ],
      "projectId": "38044",
      "companyCode": [
      "12489",
      "AB033",
      "90353"
      ],
      "projectId": "103448",
      "companyCode": [
      "62030"
      ]
      }

      API Endpoint: Retrieve List of Employees

      Endpoint:

      https://clientapi.frankcrum.com/v1/clients/11010/employees

      Headers:

      ▪ client_id: [client-id-here]
      ▪ client_secret: [client-secret-here]

      Path Parameters:

      ▪ ProjectId: The ID of the project (e.g., 11010).

      Example cURL Request:

      curl --location 'https://clientapi.frankcrum.com/v1/clients/11010/employees' \
      --header 'client_id: [client-id-here]' \
      --header 'client_secret: [client-secret-here]'

      NOTE: URL is CASE-SENSITIVE.

      Example Response:

      {
      "metadata": {
      "currentPage": "1",
      "pageSize": "1000",
      "totalCount": "535",
      "recordCount": "535"
      },
      "results": [
      {
      "companyCode": "200MR",
      "employeeId": "683ZUH0000K0",
      "firstName": "VIRGINA",
      "lastName": "BENESKO",
      "middleInitial": "",
      "preferedName": "",
      "homeAddress1": "4617 LEGENDS LN",
      "homeAddress2": "",
      "city": "ELKTON",
      "state": "FL",
      "zipCode": "320332058",
      "cellPhoneNumber": "",
      "emailAddress": "",

      "dateOfBirth": "1942-09-16T00:00:00",
      "socialSecurityNumber": "005653161",
      "gender": "F",
      "genderCodeDescription": "Female",
      "employementStatusCode": "T",
      "employmentStatusDescription": "Terminated"
      },
      {
      "companyCode": "200MR",
      "employeeId": "683ZUI0000K0",
      "firstName": "NATALIE",
      "lastName": "HURTADO",
      "middleInitial": "",
      "preferedName": "",
      "homeAddress1": "2202 PROSPER ST",
      "homeAddress2": "",
      "city": "PALATKA",
      "state": "FL",
      "zipCode": "321775541",
      "cellPhoneNumber": "",
      "emailAddress": "",
      "dateOfBirth": "1962-10-05T00:00:00",
      "socialSecurityNumber": "005653883",
      "gender": "F",
      "genderCodeDescription": "Female",
      "employementStatusCode": "T",
      "employmentStatusDescription": "Terminated"
      }
      ]
      }

      Purpose

      The metadata in the API response provides essential information about the data returned in the results. It includes details about pagination and the total number of records available:

      • currentPage: Indicates which page of results is currently being viewed, useful for navigating through large sets of data.
      • pageSize: Specifies the number of records included on each page, allowing for controlled data retrieval.
      • totalCount: Shows the total number of records available, giving a sense of the data's overall size.
      • recordCount: Represents the number of records returned in the current response, reflecting how many items are on the current page.

      This metadata helps manage and navigate large datasets by providing context about the structure and scope of the returned data.

      The results section in the API response contains a list of employee records, each represented by an object with various fields. These fields provide detailed information about each employee, including personal details, contact information, employment status, and more. This structured data allows for comprehensive tracking and management of employee information within the system.

      Field Description
      companyCode The company code associated with the employee (e.g., 200MR).
      employeeId A unique identifier for the employee (e.g., 683ZUH0000K0).
      firstName The first name of the employee (e.g., VIRGINA).
      lastName The last name of the employee (e.g., BENESKO).
      middleInitial The middle initial of the employee (if any).
      preferedName The preferred name of the employee (if any).
      homeAddress1 The first line of the employee’s home address (e.g., 4617 LEGENDS LN).
      homeAddress2 The second line of the employee’s home address (if any).
      city The city of the employee’s residence (e.g., ELKTON).
      state The state of the employee’s residence (e.g., FL).
      zipCode The ZIP code of the employee’s residence (e.g., 320332058).
      cellPhoneNumber The cell phone number of the employee (if any).
      emailAddress The email address of the employee (if any).
      dateOfBirth The employee’s date of birth (e.g., 1942-09-16T00:00:00).
      socialSecurityNumber The employee’s Social Security Number (e.g., 005653161).
      gender The gender of the employee (e.g., F).
      genderCodeDescription The description of the gender code (e.g., Female).
      employementStatusCode The employment status code (e.g., T).
      employmentStatusDescription The description of the employment status (e.g., Terminated).

      API Endpoint: Retrieve Employee

      Endpoint:

      https://clientapi.frankcrum.com/v1/clients/{ProjectId}/employees/{EmployeeId}

      Headers:

      ▪ client_id: [client-id-here]
      ▪ client_secret: [client-secret-here]

      Path Parameters:

      ▪ ProjectId: The ID of the project (e.g., 110110).
      ▪ EmployeeId: The ID of the employee (e.g., 100AAA0000A0).

      Example cURL Request:

      curl --location
      'https://clientapi.frankcrum.com/v1/clients/{ProjectId}/employees/{EmployeeId}' \
      --header 'client_id: [client-id-here]' \
      --header 'client_secret: [client-secret-here]'

      NOTE: URL is CASE-SENSITIVE.

      Example Response:

      [
      {
      "companyCode": "200MR",
      "employeeId": "683ZUH0000K0",
      "firstName": "VIRGINA",
      "lastName": "BENESKO",
      "middleInitial": "",
      "preferedName": "",
      "homeAddress1": "4617 LEGENDS LN",
      "homeAddress2": "",
      "city": "ELKTON",
      "state": "FL",
      "zipCode": "320332058",
      "cellPhoneNumber": "",
      "emailAddress": "",
      "dateOfBirth": "1942-09-16T00:00:00",
      "socialSecurityNumber": "005653161",
      "gender": "F",
      "genderCodeDescription": "Female",
      "employmentStatusCode": "T",

      "employmentStatusDescription": "Terminated"
      }
      ]
      Field Description
      companyCode The company code associated with the employee (e.g., 200MR).
      employeeId A unique identifier for the employee (e.g., 683ZUH0000K0).
      firstName The first name of the employee (e.g., VIRGINA).
      lastName The last name of the employee (e.g., BENESKO).
      middleInitial The middle initial of the employee (if any).
      preferedName The preferred name of the employee (if any).
      homeAddress1 The first line of the employee’s home address (e.g., 4617 LEGENDS LN).
      homeAddress2 The second line of the employee’s home address (if any).
      city The city of the employee’s residence (e.g., ELKTON).
      state The state of the employee’s residence (e.g., FL).
      zipCode The ZIP code of the employee’s residence (e.g., 320332058).
      cellPhoneNumber The cell phone number of the employee (if any).
      emailAddress The email address of the employee (if any).
      dateOfBirth The employee’s date of birth (e.g., 1942-09-16T00:00:00).
      socialSecurityNumber The employee’s Social Security Number (e.g., 005653161).
      gender The gender of the employee (e.g., F).
      genderCodeDescription The description of the gender code (e.g., Female).
      employementStatusCode The employment status code (e.g., T).
      employmentStatusDescription The description of the employment status (e.g., Terminated).

      API Endpoint: Retrieve Employee - Employment Detail

      Endpoint:

      https://clientapi.frankcrum.com/v1/clients/{ProjectId}/employees/{EmployeeId}/employment-detail

      Headers:

      ▪ client_id: [client-id-here]
      ▪ client_secret: [client-secret-here]

      Path Parameters:

      ▪ ProjectId: The ID of the project (e.g., 110110).
      ▪ EmployeeId: The ID of the employee (e.g., 100AAA0000A0).

      Example cURL Request:

      curl --location
      'https://clientapi.frankcrum.com/v1/clients/{ProjectId}/emploees/{EmployeeId}/employment-detail' \
      --header 'client_id: [client-id-here]' \
      --header 'client_secret: [client-secret-here]'

      NOTE: URL is CASE-SENSITIVE.

      Example Response:

      [
      {
      "companyCode": "200MR",
      "employeeId": "683ZUH0000K0",
      "employeeNumber": "000000001",
      "employmentType": "F",
      "employmentTypeDescription": "Full Time",
      "employmentStatusCode": "T",
      "employmentStatusDescription": "Terminated",
      "employmentStatusEffectiveDate": "2014-10-12T00:00:00",
      "employmentStartDate ": "2003-01-05T00:00:00",
      "terminationDate": "2014-10-11T00:00:00",
      "terminationTypeCode": "V",
      "terminationTypeDescription": "Voluntary",
      "terminationReasonCode": "202",
      "terminationReasonDescription": "Retirement/Early Retire",
      "supervisorId": "",
      "jobTitle": "",
      "departmentCode": "0001",
      "departmentDescription": "0001",
      "wcCode": "8810",
      "jobCostingID": [
      {
      "key": "DepartmentCode",
      "value": "0001-0001"
      },
      {
      "key": "CostItem",
      "value": "Z-NONE"
      },
      {
      "key": "ClientProject",
      "value": "Z-NONE"
      }
      ],
      "ptoBalance": [
      {
      "ptoType": "Vacation",
      "accruedHours": 80,
      "usedHours": 0,
      "availableHours": 80
      },
      {
      "ptoType": "Paid Time Off",
      "accruedHours": 16,
      "usedHours": 0,
      "availableHours": 16
      }
      ],
      "deductions": [
      {
      "deductionCode": "LIFE",
      "deductionDescription": "GROUP TERM LIFE",
      "employeeDeductionAmount": 0,
      "employerDeductionAmount": 0
      }
      ],
      "payFrequencyCode": "B",
      "payFrequencyDescription": "Biweekly",
      "payTypeCode": "H",
      "payTypeDescription": "Hourly",
      "payRate": 13,
      "otherRate1": 0,
      "otherRate2": 0,
      "otherRate3": 0,
      "otherRate4": 0
      }
      ]
      Field Description
      companyCode The code representing the company the employee is associated with
      (e.g., 200MR).
      employeeId A unique identifier assigned to the employee (e.g.,683ZUH0000K0).
      employeeNumber The internal employee number (e.g., 000000001).
      employmentType A code representing the type of employment (e.g., F).
      employmentTypeDescription A description of the employment type (e.g., Full Time).
      employmentStatusCode A code representing the employment status of the employee (e.g., T).
      employmentStatusDescription A description of the employment status (e.g., Terminated).
      employmentStatusEffectiveDate The date when the employment status became effective (e.g., 2014-10-12T00:00:00).
      employmentStartDate The date when the employee started employment (e.g.,2003-01-05T00:00:00).
      terminationDate The date when the employee was terminated (e.g.,2014-10-11T00:00:00).
      terminationTypeCode A code representing the type of termination (e.g., V).
      terminationTypeDescription A description of the termination type (e.g., Voluntary).
      terminationReasonCode A code representing the reason for termination (e.g., 202).
      terminationReasonDescription A description of the termination reason (e.g., Retirement/EarlyRetire).
      supervisorId The ID of the employee's supervisor, if available.
      jobTitle The job title of the employee, if available.
      departmentCode The code of the department the employee is associated with (e.g., 0001).
      departmentDescription A description of the department (e.g., 0001).
      wcCode The workers' compensation code (e.g., 8810).
      jobCostingID A list of key-value pairs representing job costing information.
      ptoBalance A list of PTO (Paid Time Off) balances, including types, accrued hours, used hours, and available hours.
      deductions A list of deductions, including codes, descriptions, and amounts for employee and employer.
      payFrequencyCode A code representing the pay frequency (e.g., B).
      payFrequencyDescription A description of the pay frequency (e.g., Biweekly).
      payTypeCode A code representing the pay type (e.g., H).
      payTypeDescription A description of the pay type (e.g., Hourly).
      payRate The pay rate of the employee (e.g., 13).
      otherRate1 Other rate 1, if applicable (e.g., 0).
      otherRate2 Other rate 2, if applicable (e.g., 0).
      otherRate3 Other rate 3, if applicable (e.g., 0).
      otherRate4 Other rate 4, if applicable (e.g., 0).

      API Endpoint: Retrieve Account Information

      Endpoint:

      https://clientapi.frankcrum.com/v1/clients/{ProjectId}/account-info/{Date}

      Headers:

      ▪ client_id: [client-id-here]
      ▪ client_secret: [client-secret-here]

      Path Parameters:

      ▪ ProjectId: The ID of the project (e.g., 11010).
      ▪ Date: Date of snapshot to return (e.g., 2021-01-14).

      Example cURL Request:

      curl --location 'https://clientapi.frankcrum.com/v1/clients/{ProjectId}/accountinfo/{Date}' \
      --header 'client_id: [client-id-here]' \
      --header 'client_secret: [client-secret-here]'

      NOTE: Date Parameter Format

      When providing dates in the parameters, the date must be formatted as YYYY-MM-DD. This format requires:

      ▪ YYYY: A 4-digit year (e.g., 2021).
      ▪ MM: A 2-digit month, where January is 01 and December is 12.
      ▪ DD: A 2-digit day, where the 1st of the month is 01 and the 31st is 31.

      Examples:

      Correct Format:

      ▪ January 5, 2021: 2021-01-05
      ▪ October 11, 2014: 2014-10-11
      ▪ December 31, 1999: 1999-12-31

      Incorrect Format Examples:

      ▪ 2021-1-5 (Month and day must be 2 digits: 2021-01-05)
      ▪ 21-01-05 (Year must be 4 digits: 2021-01-05)
      ▪ 2021/01/05 (Must use hyphens - as separators: 2021-01-05)

      Ensure that all date parameters adhere to this YYYY-MM-DD format to avoid errors in processing requests.

      NOTE: Date must match a pay date otherwise no data will be returned.

      Example Response:

      [
      {
      "companyCode": "200MR",
      "employeeId": "7GHF770000K0",
      "employeeNumber": "000000100",
      "firstName": "DAVID",
      "lastName": "DRYSDALE",
      "gl_Account": "",
      "gl_AccountDescription": "Unmapped",
      "gl_JournalEntryType": "",
      "payGroup": "200MRB",
      "payGroupDescription": "200MR ST AUGUSTINE ALLIGA",
      "payrollCode": "K20",
      "payrollCodeDesription": "HEALTH P/T",
      "payrollAmount": 209.23,
      "periodStartDate": "2020-12-27T00:00:00",
      "periodEndDate": "2021-01-09T00:00:00",
      "payDate": "2021-01-14T00:00:00",
      "payPeriodControl": "202101141",
      "department": "0001",
      "departmentDescription": "0001",
      "costItem": "NONE",
      "costItemDescription": "NONE",
      "clientProject": "NONE",
      "clientProjectDescription": "NONE",
      "jobCode": "8810",
      "jobCodeDescription": "8810",
      "location": "000234",
      "locationDescription": "200MR-ST AUGUSTINE ALLIGA",
      "project": "Z",
      "projectDescription": "<None>",
      "invoiceNumber": "",
      "invoiced": "N"
      },
      {
      "companyCode": "200MR",
      "employeeId": "7GHF770000K0",
      "employeeNumber": "000000100",
      "firstName": "DAVID",
      "lastName": "DRYSDALE",
      "gl_Account": "",
      "gl_AccountDescription": "Unmapped",
      "gl_JournalEntryType": "",
      "payGroup": "200MRB",
      "payGroupDescription": "200MR ST AUGUSTINE ALLIGA",
      "payrollCode": "K22",
      "payrollCodeDesription":"DENTAL P/T",
      "payrollAmount": 70.44,
      "periodStartDate": "2020-12-27T00:00:00",
      "periodEndDate": "2021-01-09T00:00:00",
      "payDate": "2021-01-14T00:00:00",
      "payPeriodControl": "202101141",
      "department": "0001",
      "departmentDescription": "0001",
      "costItem": "NONE",
      "costItemDescription": "NONE",
      "clientProject": "NONE",
      "clientProjectDescription": "NONE",
      "jobCode": "8810",
      "jobCodeDescription": "8810",
      "location": "000234",
      "locationDescription": "200MR-ST AUGUSTINE ALLIGA",
      "project": "Z",
      "projectDescription": "<None>",
      "invoiceNumber": "",
      "invoiced": "N"
      }
      ]
      Field Description
      companyCode The code representing the company (e.g., 200MR).
      employeeId A unique identifier assigned to the employee (e.g., 7GHF770000K0).
      employeeNumber The internal employee number (e.g., 000000100).
      firstName The first name of the employee (e.g., DAVID).
      lastName The last name of the employee (e.g., DRYSDALE).
      gl_Account The general ledger account associated with the entry (if available).
      gl_AccountDescription A description of the general ledger account (e.g., Unmapped).
      gl_JournalEntryType The type of journal entry for the general ledger (if available).
      payGroup The pay group code (e.g., 200MRB).
      payGroupDescription A description of the pay group (e.g., 200MR ST AUGUSTINE ALLIGA).
      payrollCode The payroll code associated with the entry (e.g., K20).
      payrollCodeDesription A description of the payroll code (e.g., HEALTH P/T).
      payrollAmount The payroll amount for the entry (e.g., 209.23).
      periodStartDate The start date of the payroll period (e.g., 2020-12-27T00:00:00).
      periodEndDate The end date of the payroll period (e.g., 2021-01-09T00:00:00).
      payDate The date the payroll was issued (e.g., 2021-01-14T00:00:00).
      payPeriodControl The control number for the pay period (e.g., 202101141).
      department The department code (e.g., 0001).
      departmentDescription A description of the department (e.g., 0001).
      costItem The cost item code (e.g., NONE).
      costItemDescription A description of the cost item (e.g., NONE).
      clientProject The client project code (e.g., NONE).
      clientProjectDescription A description of the client project (e.g., NONE).
      jobCode The job code associated with the entry (e.g., 8810).
      jobCodeDescription A description of the job code (e.g., 8810).
      location The location code (e.g., 000234).
      locationDescription A description of the location (e.g., 200MR-ST AUGUSTINE ALLIGA).
      project The project code (e.g., Z).
      projectDescription A description of the project (e.g., Zebra Park).
      invoiceNumber The invoice number associated with the entry (if available).
      invoiced Indicates whether the entry was invoiced (e.g., N).