Analyse Comms API

Analyse a communication draft against a decision profile.

API base URLhttps://backend.snap.wizer.business

POST https://backend.snap.wizer.business/api/v1/snap/comms

Headers

x-api-key: wz_live_your_api_key
Content-Type: application/json

Two Ways To Provide Profile Context

Every request must identify exactly one profile source — a snapId or a primaryCode. Never send both, and never send neither.

snapId — Use the snapId returned by Predict Profile. The backend reads the profile (and secondary profile, if one exists) directly from that snap record and, on success, creates or updates a comms record you can retrieve later.
primaryCode (+ optional secondaryCode) — Skip Predict Profile entirely and analyse against a known Decision Profile Code directly. No comms record is created or stored; the response is generated and returned immediately with commsId: null.

secondaryCode is only read when you use primaryCode. If you send it together with snapId, it is ignored — the snap's own secondary profile (if any) is used instead.

Request Body

Option A: Using `snapId`

{
  "snapId": 123,
  "messageType": "email",
  "messageText": "Hi Alex, I wanted to follow up on the renewal proposal..."
}

Option B: Using `primaryCode`

{
  "primaryCode": "DP-03",
  "secondaryCode": "DP-06",
  "messageType": "email",
  "messageText": "Hi Alex, I wanted to follow up on the renewal proposal..."
}

Fields

messageText: Required string with at least one character.
messageType: Required enum. One of outreach, text, email, internal_comms, difficult_conversation, meeting_prep.
snapId: Optional number returned by Predict Profile. Provide this or primaryCode — not both.
primaryCode: Optional string. One of the Decision Profile Codes below. Provide this or snapId — not both.
secondaryCode: Optional string. One of the Decision Profile Codes below. Only used alongside primaryCode. Cannot be DP-07 (Visionary).

API Credit Cost

Each successful call to this endpoint deducts 2 API credits from your account — whether you use snapId or primaryCode. See API Billing & Credits for how to add more.

Decision Profile Codes

Use these codes with primaryCode and secondaryCode. The same codes are also returned as primary_code / secondary_code in the Predict Profile response, so you can feed a prior prediction straight back in without storing a snapId.

Code	Profile
`DP-01`	Achiever
`DP-02`	Explorer
`DP-03`	Analyzer
`DP-04`	Guardian
`DP-05`	Deliverer
`DP-06`	Collaborator
`DP-07`	Visionary — allowed as `primaryCode` only, not as `secondaryCode`

Prefer to try it live? Try it in the Playground.

Examples

Using `snapId`

Curl

curl -X POST "https://backend.snap.wizer.business/api/v1/snap/comms" \
  -H "Content-Type: application/json" \
  -H "x-api-key: wz_live_your_api_key" \
  -d '{
  "snapId": 123,
  "messageType": "email",
  "messageText": "Hi Alex, I wanted to follow up on the renewal proposal..."
}'

JavaScript

const response = await fetch("https://backend.snap.wizer.business/api/v1/snap/comms", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "wz_live_your_api_key",
  },
  body: JSON.stringify({
  "snapId": 123,
  "messageType": "email",
  "messageText": "Hi Alex, I wanted to follow up on the renewal proposal..."
}
  ),
});

const result = await response.json();

if (!response.ok) {
  throw new Error(result.message || "Wize Snap API request failed");
}

console.log(result);

Python

import requests

url = "https://backend.snap.wizer.business/api/v1/snap/comms"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "wz_live_your_api_key",
}
payload = {
    "snapId": 123,
    "messageType": "email",
    "messageText": "Hi Alex, I wanted to follow up on the renewal proposal..."
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
result = response.json()

if not response.ok:
    raise Exception(result.get("message", "Wize Snap API request failed"))

print(result)

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
  "snapId": 123,
  "messageType": "email",
  "messageText": "Hi Alex, I wanted to follow up on the renewal proposal..."
}`)

	req, err := http.NewRequest("POST", "https://backend.snap.wizer.business/api/v1/snap/comms", bytes.NewBuffer(payload))
	if err != nil {
		panic(err)
	}

	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-api-key", "wz_live_your_api_key")

	client := &http.Client{}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}

	var result map[string]any
	if err := json.Unmarshal(body, &result); err != nil {
		panic(err)
	}

	if res.StatusCode < 200 || res.StatusCode >= 300 {
		panic(result["message"])
	}

	fmt.Println(result)
}

Using `primaryCode`

Curl

curl -X POST "https://backend.snap.wizer.business/api/v1/snap/comms" \
  -H "Content-Type: application/json" \
  -H "x-api-key: wz_live_your_api_key" \
  -d '{
  "primaryCode": "DP-03",
  "secondaryCode": "DP-06",
  "messageType": "email",
  "messageText": "Hi Alex, I wanted to follow up on the renewal proposal..."
}'

JavaScript

const response = await fetch("https://backend.snap.wizer.business/api/v1/snap/comms", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "wz_live_your_api_key",
  },
  body: JSON.stringify({
  "primaryCode": "DP-03",
  "secondaryCode": "DP-06",
  "messageType": "email",
  "messageText": "Hi Alex, I wanted to follow up on the renewal proposal..."
}
  ),
});

const result = await response.json();

if (!response.ok) {
  throw new Error(result.message || "Wize Snap API request failed");
}

console.log(result);

Python

import requests

url = "https://backend.snap.wizer.business/api/v1/snap/comms"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "wz_live_your_api_key",
}
payload = {
    "primaryCode": "DP-03",
    "secondaryCode": "DP-06",
    "messageType": "email",
    "messageText": "Hi Alex, I wanted to follow up on the renewal proposal..."
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
result = response.json()

if not response.ok:
    raise Exception(result.get("message", "Wize Snap API request failed"))

print(result)

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
  "primaryCode": "DP-03",
  "secondaryCode": "DP-06",
  "messageType": "email",
  "messageText": "Hi Alex, I wanted to follow up on the renewal proposal..."
}`)

	req, err := http.NewRequest("POST", "https://backend.snap.wizer.business/api/v1/snap/comms", bytes.NewBuffer(payload))
	if err != nil {
		panic(err)
	}

	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-api-key", "wz_live_your_api_key")

	client := &http.Client{}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}

	var result map[string]any
	if err := json.Unmarshal(body, &result); err != nil {
		panic(err)
	}

	if res.StatusCode < 200 || res.StatusCode >= 300 {
		panic(result["message"])
	}

	fmt.Println(result)
}

Success Response

If the snap has no existing comms record, the backend creates one. If the snap already has a comms record, the backend updates it and returns the existing commsId.

{
  "success": true,
  "message": "Comms generated successfully",
  "data": {
    "commsId": 456,
    "commsResponse": {
      "strengths": [
        "The message is concise and clearly explains the reason for follow-up."
      ],
      "risks": ["It may need more evidence for an Analyzer profile."],
      "suggestions": ["Add one concrete data point and a clear next step."],
      "rewrite": "Hi Alex, I wanted to follow up on the renewal proposal and share the two metrics most relevant to the decision..."
    }
  },
  "statusCode": 201,
  "timestamp": "2026-06-23T13:30:00.000Z",
  "error": null
}

If the upstream response is empty or cannot be parsed into sections, the arrays can be empty and rewrite can be an empty string.

{
  "success": true,
  "message": "Comms generated successfully",
  "data": {
    "commsId": 456,
    "commsResponse": {
      "strengths": [],
      "risks": [],
      "suggestions": [],
      "rewrite": ""
    }
  },
  "statusCode": 201,
  "timestamp": "2026-06-23T13:30:00.000Z",
  "error": null
}

When you use primaryCode instead of snapId, no comms record is created or updated, so commsId is always null:

{
  "success": true,
  "message": "Comms generated successfully",
  "data": {
    "commsId": null,
    "commsResponse": {
      "strengths": [
        "The message is concise and clearly explains the reason for follow-up."
      ],
      "risks": ["It may need more evidence for an Analyzer profile."],
      "suggestions": ["Add one concrete data point and a clear next step."],
      "rewrite": "Hi Alex, I wanted to follow up on the renewal proposal and share the two metrics most relevant to the decision..."
    }
  },
  "statusCode": 201,
  "timestamp": "2026-06-23T13:30:00.000Z",
  "error": null
}

Error Responses

Missing Or Invalid API Key

API-key validation happens in middleware, so this response is returned before the global response interceptor.

{
  "message": "Invalid or inactive api key",
  "error": "Invalid or inactive api key",
  "statusCode": 401
}

Validation Error

Returned for missing/invalid messageText or messageType.

{
  "success": false,
  "message": "Message text must be at least 1 character long",
  "error": "Message text must be at least 1 character long",
  "statusCode": 400,
  "timestamp": "2026-06-23T13:30:00.000Z"
}

Invalid Message Type

{
  "success": false,
  "message": "Message type must be one of: outreach, text, email, internal_comms, difficult_conversation, meeting_prep",
  "error": "Message type must be one of: outreach, text, email, internal_comms, difficult_conversation, meeting_prep",
  "statusCode": 400,
  "timestamp": "2026-06-23T13:30:00.000Z"
}

Invalid Profile Code

Returned when primaryCode or secondaryCode is not one of the documented codes.

{
  "success": false,
  "message": "primaryCode must be one of: DP-01, DP-02, DP-03, DP-04, DP-05, DP-06, DP-07",
  "error": "primaryCode must be one of: DP-01, DP-02, DP-03, DP-04, DP-05, DP-06, DP-07",
  "statusCode": 400,
  "timestamp": "2026-06-23T13:30:00.000Z"
}

Missing Profile Reference

Returned when neither snapId nor primaryCode is provided.

{
  "success": false,
  "message": "Provide either snapId or primaryCode.",
  "error": "Provide either snapId or primaryCode.",
  "statusCode": 400,
  "timestamp": "2026-06-23T13:30:00.000Z"
}

Conflicting Profile Reference

Returned when both snapId and primaryCode are provided in the same request.

{
  "success": false,
  "message": "Provide only one of snapId or primaryCode, not both.",
  "error": "Provide only one of snapId or primaryCode, not both.",
  "statusCode": 400,
  "timestamp": "2026-06-23T13:30:00.000Z"
}

Restricted Secondary Code

Returned when secondaryCode is DP-07 (Visionary), which is not allowed as a secondary profile.

{
  "success": false,
  "message": "secondaryCode cannot be 'DP-07' (Visionary).",
  "error": "secondaryCode cannot be 'DP-07' (Visionary).",
  "statusCode": 400,
  "timestamp": "2026-06-23T13:30:00.000Z"
}

Snap Not Found

Only applies when using snapId.

{
  "success": false,
  "message": "Before adding comms, you need to create a snap first.",
  "error": "Before adding comms, you need to create a snap first.",
  "statusCode": 404,
  "timestamp": "2026-06-23T13:30:00.000Z"
}

Snap Belongs To Another User

Only applies when using snapId.

{
  "success": false,
  "message": "You are not authorized to add comms to this snap",
  "error": "You are not authorized to add comms to this snap",
  "statusCode": 401,
  "timestamp": "2026-06-23T13:30:00.000Z"
}

Insufficient API Credits

Returned when an API key request is made and the account has no remaining API credits.

{
  "success": false,
  "message": "Insufficient API credits. Please add more credits to your account to continue.",
  "error": "Insufficient API credits. Please add more credits to your account to continue.",
  "statusCode": 400,
  "timestamp": "2026-06-23T13:30:00.000Z"
}

Upstream Generation Failed

{
  "success": false,
  "message": "Failed to generate comms. Please try again later.",
  "error": "Failed to generate comms. Please try again later.",
  "statusCode": 500,
  "timestamp": "2026-06-23T13:30:00.000Z"
}

Rate Limit Exceeded

See Rate Limiting for the request limit, response headers, and IP-based tracking.

{
  "success": false,
  "message": "ThrottlerException: Too Many Requests",
  "error": "ThrottlerException: Too Many Requests",
  "statusCode": 429,
  "timestamp": "2026-06-23T13:30:00.000Z"
}

Headers​

Two Ways To Provide Profile Context​

Request Body​

Option A: Using snapId​

Option B: Using primaryCode​

Fields​

API Credit Cost​

Decision Profile Codes​

Examples​

Using snapId​

Curl

JavaScript

Python

Go

Using primaryCode​

Curl

JavaScript

Python

Go

Success Response​

Error Responses​

Missing Or Invalid API Key​

Validation Error​

Invalid Message Type​

Invalid Profile Code​

Missing Profile Reference​

Conflicting Profile Reference​

Restricted Secondary Code​

Snap Not Found​

Snap Belongs To Another User​

Insufficient API Credits​

Upstream Generation Failed​

Rate Limit Exceeded​

Headers

Two Ways To Provide Profile Context

Request Body

Option A: Using `snapId`

Option B: Using `primaryCode`

Fields

API Credit Cost

Decision Profile Codes

Examples

Using `snapId`

Using `primaryCode`

Success Response

Error Responses

Missing Or Invalid API Key

Validation Error

Invalid Message Type

Invalid Profile Code

Missing Profile Reference

Conflicting Profile Reference

Restricted Secondary Code

Snap Not Found

Snap Belongs To Another User

Insufficient API Credits

Upstream Generation Failed

Rate Limit Exceeded