Valley
Integrations

API Setup

Valley's Public API V1 is a JSON/HTTP REST API for basic campaign management.

Full Interactive Docs Here →

Recommended way to use it (agent + API key)

If the customer is using an AI agent/internal assistant, point it to https://api.joinvalley.co/docs/json and provide:

  1. API key in header: x-api-key: <YOUR_API_KEY>

  2. Base URL: https://api.joinvalley.co

  3. The workflow goal (example: “list campaigns, add leads, then fetch analytics”)

That is the fastest/easiest path because the agent can read the full OpenAPI schema directly.

Authentication

All requests must include an API key (find this via Settings > Integrations):

  • Header: x-api-key: <your_api_key>

  • API keys are scoped to a single Valley user (owner-scoped).

API key lifecycle

  • Format: API keys currently look like valley_<hex>.

  • Storage: Treat the key like a password. Do not commit it to source control.

  • Rotation/revocation: Regenerate the key in the Valley app to rotate it. Regeneration invalidates the previous key immediately.

  • Expiration: Keys do not currently expire automatically.

If you don't have access to generate a key in-app, contact Valley support.

Endpoint inventory

All customer-facing endpoints are under /public/v1:

Analytics

  • GET /public/v1/analytics/overview

  • GET /public/v1/campaigns/:campaignId/analytics

Approvals

  • GET /public/v1/approvals/messages

  • POST /public/v1/approvals/messages/:messageId/approve

  • POST /public/v1/approvals/messages/:messageId/unapprove

  • POST /public/v1/approvals/messages/:messageId/unschedule

  • POST /public/v1/approvals/messages/batch-approve

  • POST /public/v1/approvals/messages/batch-unapprove

  • POST /public/v1/approvals/messages/batch-unschedule

  • POST /public/v1/approvals/messages/batch-read-status

Campaign lifecycle

  • POST /public/v1/campaigns/:campaignId/start

  • POST /public/v1/campaigns/:campaignId/pause

  • POST /public/v1/campaigns/:campaignId/resume

  • POST /public/v1/campaigns/:campaignId/archive

Campaigns + prospects + imports

  • GET /public/v1/campaigns/get-all

  • POST /public/v1/campaigns

  • PATCH /public/v1/campaigns/:campaignId

  • GET /public/v1/campaigns/:campaignId

  • POST /public/v1/campaigns/add-lead-to-campaign

  • GET /public/v1/campaigns/:campaignId/prospects

  • GET /public/v1/import-jobs/:jobId

Inbox

  • GET /public/v1/inbox/conversations

  • POST /public/v1/inbox/conversations/:conversationId/read

  • POST /public/v1/inbox/conversations/:conversationId/unread

  • POST /public/v1/inbox/conversations/:conversationId/archive

  • POST /public/v1/inbox/conversations/:conversationId/unarchive

  • POST /public/v1/inbox/conversations/batch-read-status

  • POST /public/v1/inbox/conversations/batch-archive

Warmlist

  • GET /public/v1/warmlist

  • GET /public/v1/warmlist/:workspaceId/stats

  • GET /public/v1/warmlist/:workspaceId/followers

  • GET /public/v1/warmlist/:workspaceId/viewers

  • GET /public/v1/warmlist/:workspaceId/engagers

Workspace + user + metadata

  • GET /public/v1/workspaces

  • GET /public/v1/workspaces/:workspaceId/users

  • GET /public/v1/workspace-products

  • GET /public/v1/users/me

  • GET /public/v1/templates

  • GET /public/v1/writing-styles

Recent validation/contract behavior

  • Batch endpoints reject unknown fields with 400 Unknown field: ....

  • GET /public/v1/analytics/overview requires startDate, endDate, and workspaceId (returns 400 when any are missing).

  • view is no longer required for:

    • GET /public/v1/approvals/messages

    • GET /public/v1/inbox/conversations

Error handling guidance

  • 2xx: success

  • 4xx: request/auth/data issue — fix request before retrying

  • 429 and 5xx: retry with exponential backoff + jitter

Requests

  • All request bodies are JSON.

  • Set Content-Type: application/json for POST requests.

  • We recommend setting a descriptive User-Agent so support can identify your integration.

Responses

  • All responses are JSON.

  • Timestamps are returned as ISO 8601 strings in UTC (e.g., 2026-03-04T21:16:39.068Z).

Pagination

List endpoints use offset pagination:

  • limit (1–100, default 100)

  • offset (0+, default 0)

The response includes pagination.hasMore to indicate whether additional pages exist.

Rate limiting

Requests may be rate-limited.

  • When rate-limited, the API responds with 429 Too Many Requests.

  • When available, these headers describe your current window:

    • x-rate-limit-limit

    • x-rate-limit-remaining

    • x-rate-limit-reset

Retry guidance

  • For 429, retry after the time indicated by rate-limit headers (and/or Retry-After when present).

  • For 5xx, retry with exponential backoff and jitter.

  • For 4xx (other than 429), do not retry until you fix the request.

Idempotency

  • GET requests are safe to retry.

  • POST /campaigns/add-lead-to-campaign is not currently guaranteed to be idempotent. If you retry a timed-out request, you may enqueue duplicate work.

If you need stronger guarantees, use a client-side idempotency strategy (e.g., track (campaignId, linkedinProfileUrl) and avoid re-sending the same request).

Support/troubleshooting

When contacting support about an API request, include:

  • The full request path (e.g., /public/v1/campaigns/get-all)

  • The timestamp (UTC) and approximate time window

  • HTTP status code and response body

  • The cf-ray header value from the response (Cloudflare request ID)

  • Questions? Email us: [email protected]

Was this helpful?
Was this helpful?