mycarrierpackets-api

name	mycarrierpackets-api
description	This skill should be used when the user asks to 'integrate with MyCarrierPackets', 'set up MCP API', 'onboard carriers', 'Intellivite invitation', 'monitor carriers', 'Assure Advantage', 'get carrier data', 'retrieve COI', 'get W9', 'carrier risk assessment', 'check completed packets', 'block carrier', 'find associated carriers', 'fraud check', 'VIN verification', or when implementing TMS carrier management features. Provides comprehensive guidance for MyCarrierPackets API authentication, carrier invitations, data retrieval, monitoring, blocking, fraud detection, and document management.
keywords	["mcp","mycarrierpackets","carrier","tms","api","oauth2","monitoring","intellivite","fraud","vin","coi","w9"]
disable-model-invocation	false
user-invocable	true

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/.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. [e-mail], [e-mail].
• 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).