Request

Response

    Retrieves a financial record for a specific subcontractor. Financials
    GET

    financials/{companyId}

    Retrieve a specific record of financial and safety data, processed in TradeTapp and based on the data input by a subcontractor during the completion of their questionnaire.

    Resource Information

    Method and URI
    GET
    https://developer.api.autodesk.com/construction/tradetapp/v2/financials/{companyId}
    Authentication Context
    User context required
    Required OAuth Scopes
    data:read
    Data Format
    JSON

    Request

    Headers

    Authorization*
    string
    Must be Bearer <token>, where <token> is a three-legged access token obtained via an Authorization Code flow.
    general-contractor-company-id
    string
    This header is required only for users who belong to a parent enterprise company in TradeTapp. It specifies the BuildingConnected company ID of the child general contractor company for which the request should be performed. Otherwise, it is impossible to know for which child general contractor company the user intends to perform the request.

    For users who do not belong to a parent enterprise company, this header is not required and should be omitted. If provided for such users, the provided value must match the user’s current general contractor company, otherwise the request will be rejected with a 400 Bad Request error.

    * Required

    Request

    URI Parameters

    companyId
    string
    The company’s BuildingConnected ID.

    Response

    HTTP Status Code Summary

    200
    OK
    OK
    400
    Bad Request
    The parameters of the requested operation are invalid.
    401
    Unauthorized
    The provided bearer token is not valid.
    403
    Forbidden
    The user or service represented by the bearer token does not have permission to perform this operation.
    404
    Not Found
    The requested resource could not be found.
    409
    Conflict
    Multiple objects were found when only one was expected.
    429
    Too Many Requests
    Rate limit exceeded; wait some time before retrying. The ‘Retry-After’ header might provide the amount of the time to wait.
    500
    Internal Server Error
    An unknown error occurred on the server.

    Response

    Body Structure (200)

    Expand all
    id
    string
    Subcontractor’s BC ID. This is a unique identifier for the company’s financial data object.
    uniqueId
    string
    The internal unique ID that is set by the GC. This may be populated from an external system via a subcontractor backlog upload.
    companyName
    string
    The name of the subcontractor’s company, as configured by the general contractor’s account settings.

    This value may correspond to one of the following, if set: companyTaxName, doingBusinessAsName, or companyNetworkName.

    companyTaxName
    string
    Name of the subcontractor’s company as given in their tax form.
    doingBusinessAsName
    string
    Doing-business-as name of the subcontractor’s company as given in their tax form.
    companyNetworkName
    string
    The name of the subcontractor’s company as it appears on the Builders Network.
    hasParentCompany
    boolean
    Indicates if the subcontractor’s company has a parent company.
    parentCompanyName
    string
    If they have one, the name of the subcontractor’s parent company.
    taxIdType
    enum:string
    The subcontractor’s tax ID type. Possible values: US_FEIN, US_SSN, CAN_BN, OTHER
    federalTaxId
    string
    The tax ID of the subcontractor’s company.
    riskEvaluationScore
    int
    Risk score generated when financial input is completed. It is based on the subcontractor’s current reported backlog position vs recommended aggregate total capacity and financial benchmarking performance. Values can range from 1 to 5 where 1 represents low risk, 2 is moderate, 3 is high, 4 is severe, and 5 means no financials.
    benchmarks
    object
    A list of metrics benchmarked against other subcontractors with data for the same financial statement year. They are represented as percentiles whose values are from 0 to 100.The score itself
    debtScore
    int
    The subcontractor’s score for the Debt financial category.
    debtYear
    int
    The year of the subcontractor’s most recent financial statement on which the Debt financial category was based.
    liquidityScore
    int
    The score for the subcontractor’s Liquidity financial category.
    liquidityYear
    int
    The year of the subcontractor’s most recent financial statement on which the Liquidity financial category was based.
    profitabilityScore
    int
    The subcontractor’s score for the Profitabliity financial category.
    profitabilityYear
    int
    The year of the subcontractor’s most recent financial statement on which the Profitability financial category was based.
    turnoverScore
    int
    The subcontractor’s score for the Turnover financial category.
    turnoverYear
    int
    The year of the subcontractor’s most recent financial statement on which the Turnover financial category was based.
    overallBenchmarkingScore
    int
    The subcontractor’s overall score as a result of applying weights to each financial category.
    overallBenchmarkingYear
    int
    The year of the subcontractor’s most recent financial statement on which the overall score was based.
    keyMetrics
    object
    Key Metrics which are summarized and visible in the subcontractors profile under the Summary tab.
    dartRates
    array: object
    A list of the subcontractor’s Days Away Restricted or Transferred scores.
    score
    number
    The score for the referenced year.
    year
    int
    The year of a specific score.
    experienceModificationRatings
    array: object
    A list of the subcontractor’s Experience Modification Rating scores.
    score
    number
    The score for the referenced year.
    year
    int
    The year of a specific score.
    recordableIncidentRates
    array: object
    A list of the subcontractor’s recordable incident rate scores.
    score
    number
    The score for the referenced year.
    year
    int
    The year of a specific score.
    aggregateTotalCapacity
    number
    TradeTapp’s recommendation for the maximum total backlog the subcontractor company should take on.
    largestProject
    number
    Pulled from the Project References question (submitted by the subcontractor via questionnaire). Used to showcase subcontractor’s prior work experience.
    largestProjectYear
    int
    Year of the subcontractor’s largest project completed.
    netCashFlow
    number
    Pulled from subcontractor’s most recent financial statement. It identifies cash in vs. cash out for the business during the prior year as a helpful indicator of financial health.
    netCashFlowYear
    int
    Year in which net cash flow was provided.
    singleProjectCapacity
    number
    TradeTapp’s recommendation for the maximum individual contract size this company should take on.
    workingCapital
    number
    Pulled from subcontractor’s most recent financial statement. Current Assets - Current Liabilities. This showcases the flexibility a business has to deploy cash or assets if necessary.
    workingCapitalYear
    int
    Year in which working capital was provided.
    statements
    array: object
    A set of financial statement data which has been processed into TradeTapp from financial PDF documents, submitted by the subcontractor.
    period
    int
    Subcontractor’s statement period
    type
    enum:string
    The subcontractor’s statement type. They can be COMPILED (Compiled/Internal), REVIEWED (CPA Reviewed), AUDITED (CPA Audited). Possible values: COMPILED, REVIEWED, AUDITED
    date
    string
    The subcontractor’s statement date
    rawData
    object
    The detail of a subcontractor’s financial statement, which was manually entered through TradeTapp’s financial input section.
    accountsPayable
    number
    Accounts payable
    accountsReceivable
    number
    Accounts receivable
    amountOfCreditUsed
    number
    Amount of credit used
    billingInExcessOfCost
    number
    Billing in excess of cost
    cashAndCashEquivalents
    number
    Cash and cash equivalents
    costInExcessOfBillings
    number
    Cost in excess of billings
    costsOfGoodsSold
    number
    Costs of goods sold
    currentLiabilities
    number
    Current liabilities
    earningsBeforeIncomeTaxes
    number
    Earnings before income taxes
    equity
    number
    Equity
    interestExpense
    number
    Interest expense
    interestIncome
    number
    Interest income
    marketableSecurities
    number
    Marketable securities
    netCashFromFinancing
    number
    Net cash from financing
    netCashFromInvestments
    number
    Net cash from investments
    netCashFromOperations
    number
    Net cash from operations
    netIncome
    number
    Net income
    revenueSales
    number
    Revenue sales
    totalAssets
    number
    Total assets
    currentAssets
    number
    Total current assets
    totalLiabilities
    number
    Total liabilities
    totalLineOfCredit
    number
    Total line of credit
    metrics
    object
    Metrics from the financial metric categories (debt, liquidity, profitability, turnover) for a subcontractor.
    accountsReceivableTurnover
    number
    An activity ratio measuring how efficiently a firm uses its assets. A higher ratio indicates a stronger ability to collect on Accounts Receivable.
    assetTurnoverRatio
    number
    Indicator of the efficiency with which a company is applying its assets in order to generate revenue.
    cashToOverbillings
    number
    Over billings are cash billed on work not yet completed. This ratio is used to identify whether the cash from billings has been collected and spent or saved as cash.
    currentRatio
    number
    Similar to quick ratio. Measures a company’s ability to pay off its short-term liabilities with its current assets. A large ratio is indicative of a strong working capital position.
    daysOfCashOnHand
    number
    The number of days that a company can continue to pay its operating expenses, given the amount of cash available and assuming no additional revenue. A high value indicates a strong cash position and ability to withstand cash flow constraints.
    debtLessCashToEquity
    number
    Same as Debt to Equity ratio, however, cash is excluded from liabilities in the ratio because cash can be used to retire a liability at any point in time, therefore this may be a better indicator of how leveraged the company is.
    debtRatio
    number
    Measures the extent of a company’s leverage. It can be used to determine the proportion of a company’s assets that are financed by debt. A high ratio indicates a heavily leveraged company.
    debtToEquity
    number
    Measurement of how much suppliers, lenders, creditors and obligors have committed to the company versus what the shareholders have committed. Answers how heavily is the company leveraged.
    equityToSales
    number
    A measurement of total equity compared to annual sales. It is better for this ratio to be high.
    equityToTotalLiabilities
    number
    Measures ratio of equity (retained earnings or profit) vs. total liabilities. It is better for this ratio to be high.
    grossProfitMargin
    number
    The gross difference between sales and cost of sales.
    netProfitMargin
    number
    The net difference between sales and cost of sales plus all operating expenses, interest, taxes and dividends.
    quickRatio
    number
    Used to gauge a company’s liquidity. The quick ratio is also known as the acid test ratio. A higher ratio indicates a stronger cash position.
    returnOnAssets
    number
    Measures how effectively assets are being used to generate profits.
    underbillingsToCurrentAssets
    number
    Percentage of a company’s current assets that is composed of work performed but not yet billed. Underbillings may be unreliable assets, therefore it is better for this ratio to be lower.
    underbillingsToWc
    number
    Percentage of a company’s working capital that is composed of work performed but not yet billed. Under billings may be poor assets, therefore it is better for this ratio to be lower.
    workingCapitalCompression
    number
    Used to measure compression in the current portion of the balance sheet. A low ratio indicates that the account is financing a substantial portion of its current assets to create a relatively small working capital position.
    workingCapitalToSales
    number
    Measurement of how effectively a company is able to generate new sales without taking on additional debt / liabilities.
    workingCapitalTurnover
    number
    A measurement comparing the depletion of working capital to the generation of sales over a given period. This provides some useful information as to how effectively a company is using its working capital to generate sales.
    customRatios
    array: object
    A list of custom financial ratios.
    name
    string
    The name of the custom ratio created in TradeTapp.
    value
    number
    The output value of the custom ratio for the subcontractor.

    Example

    OK

    Request

    curl -v 'https://developer.api.autodesk.com/construction/tradetapp/v2/financials/:companyId' \
      -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'
    

    Response

    {
      "id": "59d2b8660675250927442cbf",
      "uniqueId": "98h2fbd84k9s322ch",
      "companyName": "Gr8 Builders Inc.",
      "companyTaxName": "Gr8 Builders Inc.",
      "doingBusinessAsName": "Gr8 Builders Group",
      "companyNetworkName": "Gr8 Constructors",
      "hasParentCompany": true,
      "parentCompanyName": "BuildingConnected",
      "taxIdType": "US_FEIN",
      "federalTaxId": "123456789",
      "riskEvaluationScore": 2,
      "benchmarks": {
        "debtScore": 39,
        "debtYear": 2019,
        "liquidityScore": 49,
        "liquidityYear": 2019,
        "profitabilityScore": 34,
        "profitabilityYear": 2019,
        "turnoverScore": 47,
        "turnoverYear": 2019,
        "overallBenchmarkingScore": 43,
        "overallBenchmarkingYear": 2020
      },
      "keyMetrics": {
        "dartRates": [
          {
            "score": 1.5623,
            "year": 2019
          }
        ],
        "experienceModificationRatings": [
          {
            "score": 1.5623,
            "year": 2019
          }
        ],
        "recordableIncidentRates": [
          {
            "score": 1.5623,
            "year": 2019
          }
        ],
        "aggregateTotalCapacity": 105123000,
        "largestProject": 54000000,
        "largestProjectYear": 2019,
        "netCashFlow": 55222000,
        "netCashFlowYear": 2020,
        "singleProjectCapacity": 26586963,
        "workingCapital": 11556329,
        "workingCapitalYear": 2020
      },
      "statements": [
        {
          "period": 12,
          "type": "REVIEWED",
          "date": "2019-12-31",
          "rawData": {
            "accountsPayable": 10000,
            "accountsReceivable": 10000,
            "amountOfCreditUsed": 566323,
            "billingInExcessOfCost": 54962,
            "cashAndCashEquivalents": 8976,
            "costInExcessOfBillings": 3697,
            "costsOfGoodsSold": 110563965,
            "currentLiabilities": 963258741,
            "earningsBeforeIncomeTaxes": 856963,
            "equity": 5963236,
            "interestExpense": 98099,
            "interestIncome": 12325,
            "marketableSecurities": 6795,
            "netCashFromFinancing": 9800,
            "netCashFromInvestments": 75960,
            "netCashFromOperations": 76806,
            "netIncome": 540233,
            "revenueSales": 80635986,
            "totalAssets": 123456789,
            "currentAssets": 9888888,
            "totalLiabilities": 117493553,
            "totalLineOfCredit": 10000000
          },
          "metrics": {
            "accountsReceivableTurnover": 5.3659,
            "assetTurnoverRatio": 5.2216,
            "cashToOverbillings": 0.2574,
            "currentRatio": 1.3979,
            "daysOfCashOnHand": 277.4554,
            "debtLessCashToEquity": 3.4545,
            "debtRatio": 0.9999,
            "debtToEquity": 2.6565,
            "equityToSales": 0.2132,
            "equityToTotalLiabilities": 0.5874,
            "grossProfitMargin": 0.0563,
            "netProfitMargin": 0.0963,
            "quickRatio": 0.6532,
            "returnOnAssets": 0.0066,
            "underbillingsToCurrentAssets": 0.0563,
            "underbillingsToWc": 0.3669,
            "workingCapitalCompression": 0.2784,
            "workingCapitalToSales": 0.6326,
            "workingCapitalTurnover": 9.9999,
            "customRatios": [
              {
                "name": "Equity to Largest Project",
                "value": 0.0123
              }
            ]
          }
        }
      ]
    }
    
    Show More