API v3 · Partner Docs

Partner API Documentation

A REST API for partners to manage contacts and campaigns inside PITCHcrm. All requests are authenticated via headers and served over HTTPS.

Getting Started

Overview

Three things to know before your first request:

🔑

Get your credentials

Register your application to receive an x-api-key, x-api-secret, and x-account-id.

🌐

Choose an environment

Use the DEV base URL for testing and the LIVE URL for production.

📬

Send JSON

All request bodies must be Content-Type: application/json. All responses are JSON.

🌐 Base URLs

Development
DEV https://dev.partner.api.v3.pitchcrm.com/v3/partner/webhook
Production
LIVE https://partner.api.v3.pitchcrm.com/v3/partner/webhook
Getting Started

Authentication

All API requests must include the following three headers. Credentials are issued when you register your application with PITCHcrm.

HeaderTypeRequiredDescription
x-api-key String Yes API key provided by PITCHcrm
x-api-secret String Yes API secret provided by PITCHcrm
x-account-id String Yes Partner's encrypted account ID

📋 Example Request Headers

HTTP 
POST /v3/partner/webhook/contact/add HTTP/1.1
Host: partner.api.v3.pitchcrm.com
Content-Type: application/json
x-api-key: YOUR_API_KEY
x-api-secret: YOUR_API_SECRET
x-account-id: YOUR_ACCOUNT_ID
Getting Started

Rate Limiting

All endpoints share the same rate limit. When exceeded, the API returns HTTP 429.

⚡ 100 requests per minute per account
429 Rate limit exceeded
{
  "error": "Rate limit exceeded. Try again later."
}
Getting Started

Error Codes

These error codes are returned across all endpoints.

HTTP CodeError MessageDescription
401Invalid API credentialsAPI key or secret is incorrect
403Unauthorized account accessAccount ID mismatch
429Rate limit exceeded. Try again later.More than 100 requests per minute
500Internal server errorUnexpected server issue
Webhook

Add Contact

POST

Adds a new contact to PITCHcrm. Either email or phoneNo must be provided — an error is returned if both are missing.

🔗 Endpoint

Development
POST https://dev.partner.api.v3.pitchcrm.com/v3/partner/webhook/contact/add DEV
Production
POST https://partner.api.v3.pitchcrm.com/v3/partner/webhook/contact/add LIVE

📥 Request Body

Send as application/json. At least one of email or phoneNo is required.

JSON 
{
  "email":          "testuser@example.com",
  "firstName":      "Test",
  "lastName":       "User",
  "phoneNo":        "+1234567890",
  "addrOne":        "2nd Floor",
  "addrTwo":        "123 Main St",
  "city":           "Test City",
  "country":        "US",
  "state":          "CA",
  "zipCode":        "12345",
  "gender":         "male",
  "dateOfBirth":    "1990-01-01",
  "emailOptStatus": 0,
  "smsOptStatus":   0,
  "tag":            ["test_tag_123", "test_tag_456"]
}

📌 Field Reference

FieldTypeRequiredDescription
emailStringOptional*Contact email. Required if phoneNo not provided.
firstNameStringOptionalContact first name
lastNameStringOptionalContact last name
phoneNoStringOptional*Contact phone number. Required if email not provided.
addrOneStringOptionalAddress line 1
addrTwoStringOptionalAddress line 2
cityStringOptionalCity
countryStringOptionalCountry code — e.g. US, UK, CA, AU
stateStringOptionalState or province code
zipCodeStringOptionalZIP or postal code
genderStringOptionalmale, female, or other
dateOfBirthDateOptionalFormat: YYYY-MM-DD
emailOptStatusIntegerOptional0 = Opt-out · 1 = Opt-in
smsOptStatusIntegerOptional0 = Opt-out · 1 = Opt-in
tagArrayOptionalList of tag name strings
playerTypeArrayOptionalList of player type name strings

✅ Success Response

200 OK
{
  "status":    "success",
  "contactId": "1234567890"
}

❌ Error Responses

HTTP CodeError MessageDescription
400Either email or phoneNo is requiredBoth email and phone number are missing
401Invalid API credentialsAPI key or secret is incorrect
403Unauthorized account accessAccount ID mismatch
429Rate limit exceeded. Try again later.More than 100 requests per minute
500Internal server errorUnexpected server issue
Webhook

Campaign List

POST

Retrieves a paginated list of campaigns from PITCHcrm.

🔗 Endpoint

Development
POST https://dev.partner.api.v3.pitchcrm.com/v3/partner/webhook/campaign/list DEV
Production
POST https://partner.api.v3.pitchcrm.com/v3/partner/webhook/campaign/list LIVE

📥 Request Body

JSON 
{
  "limit": 10,
  "page":  1
}

📌 Field Reference

FieldTypeRequiredDescription
limitIntegerYesRecords per page. Maximum: 50
pageIntegerYesPage number. Must be ≥ 1

✅ Success Response

200 OK
{
  "pageNo":          1,
  "pageSize":        10,
  "totalPages":      25,
  "totalRecords":    241,
  "filteredRecords": 1,
  "campaigns": [
    {
      "Id":               12345,
      "campaignName":     "Summer Sale",
      "campaignType":     0,           // 0 = static, 1 = dynamic
      "campaignChannel":  "email",      // "email" or "sms"
      "status":           "scheduled",
      "statusColor":      "#009202",
      "active":           1,           // 0 = deleted, 1 = active
      "scheduledOn":      "2026-02-19T17:12:43.000Z",
      "scheduledTimeZone":"EST",
      "offset":           "-05:00",
      "autoResend":       0,
      "broadcastOn":      "2026-02-19T17:12:43.000Z",
      "broadcast":        1,           // 1 = ready to send
      "createdAt":        "2026-02-10T15:43:45.000Z",
      "updatedAt":        "2026-02-10T22:06:56.000Z",
      "reason":           null
    }
  ]
}

❌ Error Responses

HTTP CodeError MessageDescription
401Invalid API credentialsAPI key or secret is incorrect
403Unauthorized account accessAccount ID mismatch
429Rate limit exceeded. Try again later.More than 100 requests per minute
500Internal server errorUnexpected server issue
Webhook

Campaign Stats

POST

Fetches email and SMS delivery statistics for a specific campaign.

🔗 Endpoint

Development
POST https://dev.partner.api.v3.pitchcrm.com/v3/partner/webhook/campaign/stats DEV
Production
POST https://partner.api.v3.pitchcrm.com/v3/partner/webhook/campaign/stats LIVE

📥 Request Body

JSON 
{
  "campaignId": 12345
}

📌 Field Reference

FieldTypeRequiredDescription
campaignIdIntegerYesThe ID of the campaign to retrieve stats for

✅ Success Response

200 OK
{
  "emailStat": {
    "Sent":        14658,
    "Opened":      2268,
    "Delivered":   14537,
    "Hardbounce":  3,
    "Softbounce":  116,
    "Failed":      1,
    "Clicked":     53,
    "Unsubscribe": 6,
    "Complained":  1
  },
  "smsStat": {
    "Sent":      123,
    "Delivered": 122,
    "Failed":    0
  }
}

❌ Error Responses

HTTP CodeError MessageDescription
400CampaignId is requiredMissing campaign ID in request body
401Invalid API credentialsAPI key or secret is incorrect
403Unauthorized account accessAccount ID mismatch
429Rate limit exceeded. Try again later.More than 100 requests per minute
500Internal server errorUnexpected server issue