Request

Response

    Contacts
    GET

    contacts/{contactId}

    Retrieves information about a specific contact at the user’s company. Contacts represent the relationship between a user’s company and an invited bidder’s office (not the bidder’s company).

    Note that this relationship is updated only once per 24 hour period and is not meant to be used for real time reporting.

    Resource Information

    Method and URI
    GET
    https://developer.api.autodesk.com/construction/buildingconnected/v2/contacts/{contactId}
    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.
    * Required

    Request

    URI Parameters

    contactId
    string
    The ID of the contact.

    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.
    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
    The unique ID of the contact. This represents the relationship between your company and the bidder company’’s office and is not universally unique, unlike company ID or office ID.’

    Max length: 24

    isRemoved
    boolean
    Indicates whether this contact has been removed. Possible values:
    • true: The contact has been removed.
    • false: The contact is still available.
    officeId
    string
    The unique ID of the office.

    Max length: 24

    officeName
    string
    The name of the office.
    officePhone
    string
    The phone number of the office.
    location
    object
    The structured address details for a location.
    country
    string
    The country code of the location.
    state
    string
    The state, territory, or province code of the location.
    streetName
    string
    The street name of the location. This can be combined with streetNumber to get the street address.
    streetNumber
    string
    The numeric value of the street address. This can be combined with streetName to get the street address.
    suite
    string
    The suite number or second address line of the location.
    city
    string
    The city of the location.
    zip
    string
    The ZIP or Postal code of the location.
    complete
    string
    The complete human-readable address of the location.
    coords
    object
    The latitude and longitude coordinates of the location.
    lat
    number
    The geographic latitude of the location.
    lng
    number
    The geographic longitude of the location.
    precisionLevel
    int
    The precision with which location identifies an actual place, on a scale of 0 to 10.
    • 0 is the least precise indication, such as mapping to a country.
    • 10 is the most precise indication, such as mapping to a street number or intersection.

    This value is initially null, and is populated only after a location change.

    averageRating
    number
    Average start rating for this contact.
    qualification
    object
    Details about the qualifications of the bidder.
    qualificationStatus
    enum:string
    Indicates the qualification status of the bidder. Possible values:
    • INVITED: The bidder has been invited to submit a qualification.
    • IN_PROGRESS: The bidder has started but not yet submitted their qualification.
    • SUBMITTED: The bidder has submitted their qualification for review.
    • COMPLETED: The qualification review process is complete.
    • APPROVED: The bidder’s qualification has been approved.
    • APPROVED_WITH_EXCEPTIONS: The bidder’s qualification has been approved with noted exceptions.
    • DENIED: The bidder’s qualification has been denied.
    • EXPIRING_SOON: The bidder’s qualification is approaching its expiration date.
    • EXPIRED: The bidder’s qualification has expired.
    expiresAt
    datetime: ISO 8601
    The date and time that the qualification expires, in ISO 8601 format.
    updatedAt
    datetime: ISO 8601
    The date and time that the qualification was last updated, in ISO 8601 format.
    pqRelationshipId
    string
    The unique ID of the qualification object.
    gcCurrency
    string
    The currency used for the values of projectLimit and totalLimit, in ISO 4217 format.

    Note that this appears only for qualification limits set in TradeTapp.

    projectLimit
    number
    The amount that the contact is qualified to be awarded per project, in the currency specified by gcCurrency.
    summary
    string
    Notes about the qualification.
    totalLimit
    number
    The amount that the contact is qualified to be awarded during the qualification time frame, in the currency specified by gcCurrency.
    submissionStatus
    enum:string
    Indicates the status of the contact’s qualification submission. If the vendor is submitting on TradeTapp, their status values are converted to submissionStatus values as follows:
    • “Not Started” = NOT_STARTED
    • “In Progress” = EDITED
    • “Submitted” = SUBMITTED
    • “Complete” = COMPLETED
    • “Imported” = IMPORTED
    • Other values = NOT_INVITED

    Note that this field is not available in the BuildingConnected UI. Possible values: NOT_INVITED, IMPORTED, NOT_STARTED, COMPLETED, CREATED, EDITED, SUBMITTED

    stats
    object
    Information about the user’s historical bidding relationship with the contact. These values represent activity from the beginning of the relationship.
    awardedCount
    number
    The number of opportunities that have been awarded to the contact.
    submittedCount
    number
    The number of opportunities on which the contact submitted a bid.
    biddingCount
    number
    The number of opportunities on which the contact intended to submit a bid.
    declinedCount
    number
    The number of opportunities declined by the contact.
    invitedCount
    number
    The number of opportunities that have been sent to the contact.
    viewedCount
    number
    The number of opportunities that have been viewed by the contact.
    company
    object
    Information about a company.
    id
    string
    The unique BuildingConnected ID of the company.

    Max length: 24

    name
    string
    The name of the company.
    avatarImageUrl
    string
    The cached imgix url for the avatar image of the company.
    businessType
    array: string
    The type of business carried out by the company.
    website
    string
    The company’s official website.
    laborType
    array: string
    Specifies the labor payment structure within the company, such as Non-Union or Prevailing Wages.
    enterpriseType
    array: string
    This has been deprecated and replaced with certificates.
    companyTags
    array: string
    A list of tags assigned by your organization to categorize this company. Note that this information is private to your organization and not visible to others.
    certificates
    array: object
    A collection of certificates held by the company. This field replaces the deprecated enterpriseType field.
    id
    string
    The unique identifier for each certificate. Companies can hold multiple certificates, each with its own ID. The field is null for pending certificate suggestions.

    Max length: 24

    type
    object
    Details about the specific type of certificate.
    id
    string
    The unique ID of the certificate type.

    Max length: 24

    name
    string
    The name of the certificate type.
    agency
    object
    Details about the agency that issued the certificate.
    id
    string
    The unique identifier for the certifying agency.

    Max length: 24

    name
    string
    The name of the certifying agency.
    website
    string
    The official website URL of the certifying agency.
    number
    string
    The certificate’s unique identification number.
    expiresAt
    datetime: ISO 8601
    The date the certificate expires, in ISO 8601 format.
    fileName
    string
    The name of the digital copy of the certificate.
    updatedAt
    datetime: ISO 8601
    The date and time that the contact information was last updated, in ISO 8601 format.

    Example

    OK

    Request

    curl -v 'https://developer.api.autodesk.com/construction/buildingconnected/v2/contacts/:contactId' \
      -H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'
    

    Response

    {
      "id": "543187957b8ed9afd1cd6730",
      "isRemoved": false,
      "officeId": "5cd1269718dadedbbe76a710",
      "officeName": "San Francisco Office",
      "officePhone": "555-555-5555",
      "location": {
        "country": "US",
        "state": "CA",
        "streetName": "California St.",
        "streetNumber": "600",
        "suite": "6th Floor",
        "city": "San Francisco",
        "zip": "94108",
        "complete": "600 California St., 6th Floor, San Francisco, CA 94108",
        "coords": {
          "lat": -122.4069826,
          "lng": 37.7929546
        },
        "precisionLevel": 10
      },
      "averageRating": 3,
      "qualification": {
        "qualificationStatus": "APPROVED",
        "expiresAt": "2017-01-01T08:00:00.000Z",
        "updatedAt": "2016-01-01T08:00:00.000Z",
        "pqRelationshipId": "59d2b7f90675250927442cbe",
        "gcCurrency": "USD",
        "projectLimit": 50000,
        "summary": "Some notes",
        "totalLimit": 500000,
        "submissionStatus": "SUBMITTED"
      },
      "stats": {
        "awardedCount": 16,
        "submittedCount": 34,
        "biddingCount": 50,
        "declinedCount": 10,
        "invitedCount": 100,
        "viewedCount": 70
      },
      "company": {
        "id": "51bea397f5846f95994b1da7",
        "name": "Gr8 Builders",
        "avatarImageUrl": "https://www.example.com/",
        "businessType": [
          "Subcontractor"
        ],
        "website": "https://www.example.com",
        "laborType": [
          "Union"
        ],
        "enterpriseType": [
          "Disadvantaged Business Enterprise (DBE)"
        ],
        "companyTags": [
          "example_tag"
        ],
        "certificates": [
          {
            "id": "627074db25c97830ad3ea8c8",
            "type": {
              "id": "59d2bd7440b36a0da258f24d",
              "name": "Disadvantaged Business Enterprise (DBE)"
            },
            "agency": {
              "id": "611d794f7f063800a7274d46",
              "name": "United States Department of Transportation",
              "website": "https://www.transportation.gov/civil-rights/disadvantaged-business-enterprise"
            },
            "number": "12345",
            "expiresAt": "2014-10-03T19:00:00.000Z",
            "fileName": "certificate.pdf"
          }
        ]
      },
      "updatedAt": "2022-08-17T23:07:16.083Z"
    }
    
    Show More