Free Recommendations

Free Recommendations

A free recommendation is an organic newsletter partnership with no payment (the Grow side). Unlike paid recommendations, the same campaign can be sending (this publication recommends the other) or receiving (the other recommends this one). This resource unions both sides.

Use it to list free recommendations, fetch a single one by UUID, archive, or re-activate. Filter the list with role=sending or role=receiving; omit role for both. Each row includes role relative to this publication, plus recommending_publication next to recommended_publication. To browse newsletters available to recommend — and to add a recommendation or send a partnership request — use the Directory at grow/directory/free_recommendations. Paid recommendations live under Earn.

List free recommendations

GET https://api.sparkloop.app/v3/publications/:publication_uuid/grow/free_recommendations

Paginated. Omit status to list non-archived rows. Omit role to include both sending and receiving.

Path Parameters

Name	Type	Description
publication_uuid*	String	The publication's UUID.

Query Parameters

Name	Type	Description
status	String	Optional filter: active, awaiting_approval, or archived. Omit for all non-archived. Invalid → 400.
role	String	Optional filter: sending or receiving. Omit for both. Invalid → 400.
expand	String	recommended_publication, recommending_publication, stats.
from	String	Start date (YYYY-MM-DD) for stats.
to	String	End date (YYYY-MM-DD) for stats.

200: OK

{
  "recommendations": [
    <Recommendation Object>
  ],
  "meta": {
    "per_page": 50,
    "page": 1,
    "total_pages": 1,
    "total_recommendations": 12
  }
}

400: Bad Request

{
  "error": "Unsupported `status`. Valid values: active, awaiting_approval, archived."
}

Get free recommendation

GET https://api.sparkloop.app/v3/publications/:publication_uuid/grow/free_recommendations/:uuid

Fetch a single free recommendation this publication sends or receives.

Path Parameters

Name	Type	Description
publication_uuid*	String	The publication's UUID.
uuid*	String	The recommendation's UUID.

Query Parameters

Name	Type	Description
expand	String	recommended_publication, recommending_publication, stats.

200: OK

{
  "recommendation": <Recommendation Object>
}

404: Not Found

{
  "error": "Resource not found."
}

Archive a free recommendation

POST https://api.sparkloop.app/v3/publications/:publication_uuid/grow/free_recommendations/:free_recommendation_uuid/archive

Soft-archives the recommendation so it stops appearing in active lists. Sending archives as the partner; receiving archives as the sponsor. Reversible with re-activate when this publication archived it.

Path Parameters

Name	Type	Description
publication_uuid*	String	The publication's UUID.
free_recommendation_uuid*	String	The recommendation's UUID.

200: OK

{
  "recommendation": <Recommendation Object>
}

404: Not Found

{
  "error": "Resource not found."
}

Re-activate a free recommendation

POST https://api.sparkloop.app/v3/publications/:publication_uuid/grow/free_recommendations/:free_recommendation_uuid/reactivation

Restores a soft-archived free recommendation. Only works when this publication archived it.

Path Parameters

Name	Type	Description
publication_uuid*	String	The publication's UUID.
free_recommendation_uuid*	String	The recommendation's UUID.

200: OK

{
  "recommendation": <Recommendation Object>
}

404: Not Found

{
  "error": "Resource not found."
}

422: Unprocessable Entity

{
  "error": "This recommendation was archived by the other publication and can't be re-activated."
}