mycarrierpackets-api

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. 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).