Last updated

Expand Your Carrier Network

To add carriers to your network for asset-based tracking,

  1. Send an invitation to a carrier.
  2. The carrier accepts the invitation to connect and share data with you.
  3. Once the carrier accepts the invitation, they are considered to be connected to your network.

Send an Invitation

Send an invitation to a carrier for asset-based tracking.

Requirements

  • Carrier Identifier (VAT, SCAC, DOT_NUMBER, MC_NUMBER, P44_EU)
  • Organization Name - This is required unless the carrier already supports asset-based tracking*
  • Contact Information (email and first name at a minimum) - This is required unless the carrier already supports asset-based tracking*

*See the Get Available Tracking Methods workflow to determine if the carrier supports asset-based tracking

Workflow

  1. Prepare a POST request to /services/invitation/v1/invitations .
{
  "invitee": {
    "identifiers": [
      {
        "type": "DOT_NUMBER",
        "value": "1234567"
      }
    ],
    "organization": {
      "name": "My Trucking LLC"
    },
    "contacts": [
      {
        "email": "john@mytruckingllc.com",
        "givenName": "John",
        "familyName": "Nash",
        "locale": "en-US",
        "phone": "+14800000000"
      }
    ]
  },
  "capability": "TRUCKLOAD_ASSET_TRACKING"
}
  1. Send the request.
  2. Project44 will send an email to the carrier.
  3. When carrier signs up through the link, they will be automatically connected to your account.

Fields and Objects

ElementDescriptionTypeNotes
invitee.identifiers[].typeThe type of equipment identifier for the carrier.stringsupported values: VAT, SCAC, DOT_NUMBER, MC_NUMBER, P44_EU
invitee.identifiers[].valueThe value of the carrier identifier.string
invitee.organization.nameThe name of the organization your are inviting.string
invitee.contacts[].emailThe email of the contact.stringRequired if the carrier specified in invitee.identifiers does not have an account with project44.
invitee.contacts[].givenNameThe first name of the contact.stringRequired if the carrier specified in invitee.identifiers does not have an account with project44.
invitee.contacts[].familyNameThe last name of the contact.stringOptional.
invitee.contacts[].localeThe language used in the email sent to the carrier.stringOptional. See Supported Locales in the Appendix for valid values.
invitee.contacts[].phoneNumberThe phone number for the contact.stringOptional.
capabilityThe supported service.stringValid value is TRUCKLOAD_ASSET_TRACKING.

Expected System Response

{
    "invitee": {
        "identifiers": [
            {
                "type": "VAT",
                "value": "NL1234567890"
            }
        ],
        "organization": {
            "name": "Test Trucking LLC"
        },
        "contacts": [
            {
                "email": "my-contact@test-trucking-llc.com",
                "givenName": "John",
                "familyName": "Nash",
                "locale": "en-US",
                "phoneNumber": "+3112312313"
            }
        ]
    },
    "capability": "TRUCKLOAD_ASSET_TRACKING",
    "status": "IN_PROGRESS",
    "createdDateTime": "2024-03-18T11:27:45.465Z",
    "lastModifiedDateTime": "2024-03-18T11:27:45.465Z",
    }

Fields and Objects

ElementDescriptionTypeNotes
statusThe status of the invitation.stringValid values are IN_PROGRESS, ACCEPTED, DECLINED, CANCELED, and EXPIRED. See Invitation Statuses for more definitions of each status.
createdDateTimeThe date and time the invitiation was created.string

Errors

If there was a problem with your request, you will receive one of the following error codes:

  • 400 Invalid request
  • 401 Invalid or missing credentials
  • 403 User not authorized to perform this operation

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Check Network State

Check the status of your sent invitations.

Requirements

Workflow

  1. Prepare a GET request to /services/invitation/v1/invitations .
  2. Send the request.

Expected System Response

{
    "paginationInfo": {
        "total": 1,
        "pageSize": 10,
        "pageNumber": 1
    },
    "results": [
        {
            "invitee": {
                "identifiers": [
                    {
                        "type": "DOT_NUMBER",
                        "value": "1234567"
                    }
                ],
                "organization": {
                    "name": "My Trucking LLC"
                },
                "contacts": [
                    {
                        "email": "john@mytruckingllc.com",
                        "givenName": "John",
                        "familyName": "Nash",
                        "locale": "en-US",
                        "phone": "+14800000000"
                    }
                ]
            },
            "capability": "TRUCKLOAD_ASSET_TRACKING",
            "status": "IN_PROGRESS",
            "createdDateTime": "2023-04-25T15:29:58.946Z",
            "lastModifiedDateTime": "2023-04-25T15:29:58.946Z"
        }
    ]
}

Fields and Objects

ElementDescriptionTypeNotes
results[].invitee.identifiers[].typeThe type of equipment identifier for the carrier.stringValid value is VAT.
results[].invitee.identifiers[].valueThe value of the equipment identifier.string
results[].invitee.organization.nameThe name of the capacity provider.string
results[].invitee.contacts[].emailThe email address where an invitation was sent.string
results[].invitee.contacts[].givenNameThe first name of the contact.stringRequired if the carrier specified in invitee.identifiers does not have an account with project44.
results[].invitee.contacts[].familyNameThe last name of the contact.stringOptional.
results[].invitee.contacts[].localeThe language used in the email sent to the carrier.stringOptional. See Supported Locales in the Appendix for valid values. Default value is en-US.
results[].invitee.contacts[].phoneNumberThe phone number for the contact.stringOptional.
results[].statusThe status of the invitation.string
results[].capabilityCapability for which the invitation was created.string
results[].createdDateTimeThe date and time the invitiation was created.string

Errors

If there was a problem with your request, you will receive one of the following error codes:

  • 400 Invalid request
  • 401 Invalid or missing credentials
  • 403 User not authorized to perform this operation

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Reference Values

Supported Locals

Valid Field for *invitee.contacts.localeDescription
"bg-BG"Bulgarian - Bulgaria
"cs-CZ"Czech - Czechia
"de-DE"German - Germany
"en-US"English - United States
"es-ES"Spanish - Spain
"hu-HU"Hungarian - Hungary
"it-IT"Italian - Italy
"lt-LT"Lithuanian - Lithuania
"fr-FR"French - France
"pt-BR"Portuguese - Brazil
"pl-PL"Polish - Poland
"ro-RO"Romanian - Romania
"tr-TR"Turkish - Turkey
"uk-UA"Ukranian - Ukraine

Invitation Statuses

Definitions of invitation status (status) values.

StatusDefinition
IN_PROGRESSStatus for newly created invitation, awaiting action.
ACCEPTEDThe invitation has been accepted.
DECLINEDThe invitation has been declined by the invitee.
CANCELEDThe invitation has been canceled by the inviter.
EXPIREDInvitations are marked as expired by the platform after a certain time period in the IN_PROGRESS status.
Previous page
Next page