beehiiv Developer Documentation

curl -X POST https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/paid_recommendations/invites \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "offer_id": "rec_offer_00000000-0000-0000-0000-000000000000",
  "invited_publication_id": "pub_11111111-1111-1111-1111-111111111111",
  "invite_reason": "Our readers overlap with yours."
}'

{
  "data": {
    "id": "rec_invite_00000000-0000-0000-0000-000000000000",
    "offer_id": "rec_offer_00000000-0000-0000-0000-000000000000",
    "invited_publication_id": "pub_11111111-1111-1111-1111-111111111111",
    "status": "pending",
    "expires_at": 1761489600,
    "created_at": 1760280000,
    "updated_at": 1760280000,
    "invite_reason": "Our readers overlap with yours.",
    "reject_reason": null
  }
}

Currently in beta

This feature is currently in beta and the API is subject to change.

Invite a publication to recommend you through a live offer. The invited publication is notified and has 14 days to respond. Use the publication ID returned for a publication elsewhere in the paid recommendations API, such as applications and reporting.

A request that can’t be sent returns a 422 with one of these error codes: MONTHLY_LIMIT_REACHED when the publication has used its monthly invite limit, ALREADY_INVITED when the publication already has a pending invite to the offer, OFFER_NOT_LIVE when the offer isn’t live, or FROZEN when paid recommendations are frozen for the workspace.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"

The prefixed ID of the publication object

Request

This endpoint expects an object.

offer_idstringRequiredformat: "^(rec_offer_[0-9a-fA-F\-]+)$"

The prefixed ID of the live offer to invite the publication to.

invited_publication_idstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"

The prefixed ID of the publication to invite.

invite_reasonstringOptional

A note sent to the invited publication with the invite.

Response

Created

dataobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error