MyCarrierPackets API Integration Guide Skill

MyCarrierPackets API Integration Guide

Base URL: https://api.mycarrierpackets.com Auth: OAuth2 Bearer Token (password grant) Format: JSON default; XML with Accept: text/xml Spec: Swagger 2.0 — 23 endpoints under /api/v1/Carrier/*, all POST

References

This skill uses progressive disclosure. Read SKILL.md for orientation, then load the specific endpoint file you need.

references/endpoints/INDEX.md — Browse all 23 endpoints grouped by domain (Carrier Data, Invitations, Monitoring, Block/Unblock, Documents, Factoring). Start here when you don't know which endpoint you need.
references/TMS-INTEGRATION.md — Official numbered integration workflow: Intellivite invitations, packet polling, monitoring setup, document retrieval. Load this for end-to-end integration architecture.
references/endpoints/<name>.md — 23 self-contained files (one per endpoint) with: full param table, response schema, all nested model fields inlined. Load the specific file when implementing that endpoint.

Endpoint quick map

Carrier Data

PreviewCarrier — profile + risk + cert (no packet)
GetCarrierData — full profile with packet (W9, agreements, banking, lanes…)
GetCarrierContacts — authorized/verified users
GetCarrierRiskAssessment — risk only
GetCarrierIncidentReports — incident history
GetCarrierVINVerifications — VIN status
FindAssociatedCarriers — phone/email fraud check

Invitations & Verification

EmailPacketInvitation — send Intellivite
CompletedPackets — poll for finished onboarding
RequestUserVerification — non-onboarding identity check
RequestVINVerification — VIN verify (phone only, see Non-Obvious)

Monitoring (Assure Advantage)

RequestMonitoring / CancelMonitoring — add/remove from watch list
MonitoredCarriers — list (paginated)
MonitoredCarrierData — bulk full data (paginated, expensive)
GetMonitoredCarrierContactsData — bulk contacts
GetMonitoredCarriersRiskAssessment — bulk risk
CarriersChanges — incremental change feed (paginated, primary monitoring loop)

Block / Unblock

BlockCarrier / UnblockCarrier
BlockedCarriers — list (paginated)

Documents

GetDocument — download PDF by blob name

Factoring

GetUpdatedFactoringCompanies — factoring company ID list

Authentication

See also: TMS-INTEGRATION.md § Authentication — Postman testing notes, XML response format.

Token Endpoint: POST https://api.mycarrierpackets.com/token

Content-Type: application/x-www-form-urlencoded

grant_type=password&username={integration_username}&password={integration_password}

Response: { "access_token": "eyJ...", "token_type": "bearer", "expires_in": 3600 }

Use Authorization: bearer <access_token> on every API request. Manage credentials at https://mycarrierpackets.com/IntegrationTools.

Go Client (thread-safe token caching)

type MCPClient struct {
    baseURL     string
    httpClient  *http.Client
    username    string
    password    string
    accessToken string
    tokenExpiry time.Time
    tokenMu     sync.RWMutex
}

func (c *MCPClient) getToken(ctx context.Context) (string, error) {
    c.tokenMu.RLock()
    if c.accessToken != "" && time.Now().Before(c.tokenExpiry) {
        token := c.accessToken
        c.tokenMu.RUnlock()
        return token, nil
    }
    c.tokenMu.RUnlock()

    c.tokenMu.Lock()
    defer c.tokenMu.Unlock()

    data := url.Values{}
    data.Set("grant_type", "password")
    data.Set("username", c.username)
    data.Set("password", c.password)

    req, _ := http.NewRequestWithContext(ctx, "POST", c.baseURL+"/token", strings.NewReader(data.Encode()))
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

    resp, err := c.httpClient.Do(req)
    if err != nil {
        return "", fmt.Errorf("token request: %w", err)
    }
    defer resp.Body.Close()

    var tokenResp struct {
        AccessToken string `json:"access_token"`
        ExpiresIn   int    `json:"expires_in"`
    }
    json.NewDecoder(resp.Body).Decode(&tokenResp)

    c.accessToken = tokenResp.AccessToken
    c.tokenExpiry = time.Now().Add(time.Duration(tokenResp.ExpiresIn-60) * time.Second)
    return c.accessToken, nil
}

Key Workflows

1. Carrier Invitation (Intellivite)

Official workflow: TMS-INTEGRATION.md § 1. Intellivite (§1.1 invite API, §1.2 link in TMS email, §1.3 URL to MCP) + § 2.1 Completed packets.

PreviewCarrier  →  EmailPacketInvitation  →  Poll CompletedPackets

PreviewCarrier: preload carrier email, risk, cert data before inviting
EmailPacketInvitation: include userName to link invitation to MCP user
CompletedPackets: poll every 5–15 min with a rolling time window

2. Assure Advantage Monitoring

Official workflow: TMS-INTEGRATION.md § 3. Assure Advantage — §3.1 initial/periodic sync, §3.2 batch updates (4-min minimum), §3.6 monitor/unmonitor lifecycle.

RequestMonitoring  →  Poll CarriersChanges (5–15 min)

RequestMonitoring: add carriers to watch list
CarriersChanges: incremental feed. Returns ChangeCategories[] + full CarrierDetails. Lock changed fields in TMS as read-only.
MonitoredCarrierData: full sync (paginated, expensive — use sparingly)

See TMS-INTEGRATION.md § Integration Notes for field-locking convention: when a carrier is monitored, fields should be read-only in the TMS so the data always reflects MCP's source of truth.

3. Document Retrieval

Official workflow: TMS-INTEGRATION.md § 4. Pull Carrier Packet and Assure Advantage Images — §4.1 per-document blob fetch, §4.2 full packet URL (logged-in), §4.3 full packet PDF API with separate token endpoint.

GetCarrierData  →  extract blob names  →  GetDocument (binary PDF)

Blob names come from GetCarrierData response
Pass to GetDocument to retrieve PDF bytes
Store locally; don't fetch on every request

Portal links (no API token required):

View carrier:  https://mycarrierpackets.com/CarrierInformation/DOTNumber/{dot}/DocketNumber/{mc}
Full packet:   https://mycarrierpackets.com/Download/GetCarrierPacket?DOTNumber={dot}&inline=True

For the full-packet PDF API in TMS-INTEGRATION.md § 4.3, note the token endpoint is /api/token (not the main /token from § Authentication).

4. Fraud Detection

Not covered in TMS-INTEGRATION.md; combine with the PossibleFraud and DoubleBrokering flags from PreviewCarrier for layered risk signals.

FindAssociatedCarriers?phone=X&email=Y

FindAssociatedCarriers returns all carriers sharing that phone/email across MCP+FMCSA. Each match includes PhoneAssociationTypes and EmailAssociationTypes arrays.

5. Block / Unblock Carriers

Not covered in TMS-INTEGRATION.md; this workflow is documented only in the per-endpoint references. Use it to maintain a per-customer carrier deny-list.

BlockCarrier  ↔  UnblockCarrier   |   List: BlockedCarriers

BlockCarrier / UnblockCarrier: per-customer block list
BlockedCarriers: paginated list (sync with TMS deny-list)

6. VIN Verification

Not covered in TMS-INTEGRATION.md; this is a standalone verification flow alongside RequestUserVerification.

RequestVINVerification (deliveryOption=2)  →  Poll GetCarrierVINVerifications

RequestVINVerification: initiate (phone only — see Non-Obvious)
GetCarrierVINVerifications: poll for status

Pagination

Three endpoints return pagination in the X-Pagination response header:

MonitoredCarriers (default 2500, max 5000)
BlockedCarriers (default 2500)
CarriersChanges (default 250, max 500)

MonitoredCarrierData returns pagination in the response body (pageNumber, pageSize, totalPages, totalCount).

Parse X-Pagination as JSON: {"pageNumber":1,"pageSize":250,"totalPages":10,"totalCount":2500}

func (c *MCPClient) GetAllMonitoredCarriers(ctx context.Context) ([]MonitoredCarrier, error) {
    var all []MonitoredCarrier
    page := 1
    for {
        endpoint := fmt.Sprintf("/api/v1/Carrier/MonitoredCarriers?pageNumber=%d&pageSize=2500", page)
        resp, err := c.doRequest(ctx, "POST", endpoint, nil)
        if err != nil {
            return nil, err
        }
        var carriers []MonitoredCarrier
        json.NewDecoder(resp.Body).Decode(&carriers)
        resp.Body.Close()
        all = append(all, carriers...)

        pag := resp.Header.Get("X-Pagination")
        if pag == "" || len(carriers) == 0 {
            break
        }
        var meta struct{ TotalPages int `json:"totalPages"` }
        json.Unmarshal([]byte(pag), &meta)
        if page >= meta.TotalPages {
            break
        }
        page++
    }
    return all, nil
}

Intellivite Link Formats

Source: TMS-INTEGRATION.md § 1.2 Intellivite Link in TMS-Generated Email.

# Full (recommended — pre-fills DOT+Docket, associates user)
https://mycarrierpackets.com/{IntelliviteID}/Carrier/Intellivite/{MCPUserID}/{DOT}/{MC}

# DOT only (intrastate carriers)
https://mycarrierpackets.com/{IntelliviteID}/Carrier/Intellivite/{MCPUserID}/{DOT}

# Basic (no pre-fill)
https://mycarrierpackets.com/{IntelliviteID}/Carrier/Intellivite

IntelliviteID is the customer GUID from Integration Tools. MCPUserID is the MCP username of the inviting user.

TMS UI Button Patterns

Common patterns from TMS-INTEGRATION.md § 2.3 "View Carrier" Button and § 3.3 Request COI:

View carrier:        https://mycarrierpackets.com/CarrierInformation/DOTNumber/{dot}/DocketNumber/{mc}
Request insurance:   https://mycarrierpackets.com/CarrierInformation/DOTNumber/{dot}/DocketNumber/{mc}?requestInsurance=true
Update carrier now:  call GetCarrierData in real-time (TMS-INTEGRATION § 3.4)

Error Handling

| Status | Meaning | Action | |--------|---------|--------| | 400 | Bad request | Check parameter format | | 401 | Unauthorized | Clear cached token, re-authenticate | | 403 | Forbidden | Check API permissions in Integration Tools | | 404 | Not found | Invalid DOT/Docket | | 429 | Rate limited | Increase polling interval (min 5 min) | | 500 | Server error | Retry with exponential backoff |

On 401: clear accessToken so next call re-authenticates automatically.

Non-Obvious Behaviors

VIN verification: Only deliveryOption=2 (phone) works. Email option in spec is not active. See RequestVINVerification.
requestInsurance=true query param on CarrierInformation portal URL triggers insurance request flow.
Intrastate carriers: Use IntrastateNumber param for monitoring/blocking; omit DocketNumber. Applies to RequestMonitoring, CancelMonitoring, BlockCarrier, UnblockCarrier.
notificationEmails on EmailPacketInvitation: comma-separated CC list, e.g. notify1@co.com, notify2@co.com.
Polling CarriersChanges: minimum 4-minute interval enforced upstream; 5–15 min recommended.
GetCarrierData vs PreviewCarrier: prefer PreviewCarrier for pre-invitation checks — same risk/cert data but faster since it skips packet retrieval.
All endpoints are POST even read operations (no GET). Use query string for params.
All param locations are query+header (no request bodies in this API).

Agent Skills: MyCarrierPackets API Integration Guide

Install this agent skill to your local

Skill Files