Create Proposal

Create a new proposal. Only one draft proposal is allowed per user. If a draft already exists, it will be returned instead of creating a new one.

POST /api/proposals

Create Proposal

cURL

curl --request POST \
  --url https://api.example.com/api/proposals \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "<string>",
  "description": "<string>",
  "template_id": "<string>"
}
'

200

{
  "proposal": {
    "id": "<string>",
    "proposalCode": "<string>",
    "title": "<string>",
    "description": "<string>",
    "template_id": "<string>",
    "status": "<string>",
    "created_at": "<string>",
    "updated_at": "<string>",
    "user_id": "<string>",
    "user_email": "<string>",
    "user_name": "<string>",
    "uploaded_files": {},
    "text_inputs": {},
    "metadata": {},
    "completed_steps": [
      {}
    ],
    "step_completion": {}
  },
  "message": "<string>"
}

Authentication

This endpoint requires authentication via Bearer token.

Authorization: Bearer <token>

Request Body

title · string · required

The title of the proposal.

description · string · default: ""

Optional description of the proposal.

template_id · string

Optional template ID to use for the proposal.

Response

proposal · object

The created or existing proposal object.

Show Proposal Object

id · string

Unique proposal identifier (UUID).

proposalCode · string

Human-readable proposal code (format: PROP-YYYYMMDD-XXXX).

title · string

The title of the proposal.

description · string

The description of the proposal.

template_id · string

The template ID if specified.

status · string

Current status of the proposal (e.g., “draft”).

created_at · string

ISO 8601 timestamp of when the proposal was created.

updated_at · string

ISO 8601 timestamp of the last update.

user_id · string

The ID of the user who owns the proposal.

user_email · string

The email of the user who owns the proposal.

user_name · string

The name of the user who owns the proposal.

uploaded_files · object

Dictionary of uploaded files organized by category.

text_inputs · object

Dictionary of text inputs provided by the user.

metadata · object

Additional metadata including analysis results and status flags.

completed_steps · array

Array of step numbers that have been completed (e.g., [1, 2]).

step_completion · object

Detailed completion status for each step with substatus information.

message · string

Optional message, present when returning an existing draft (“Returning existing draft proposal”).

Example Request

cURL

curl -X POST https://api.igadregion.org/api/proposals \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Climate Resilience in East Africa",
    "description": "Proposal for improving climate adaptation strategies"
  }'

Response Examples

New Proposal Created

{
  "proposal": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "proposalCode": "PROP-20260304-A1B2",
    "title": "Climate Resilience in East Africa",
    "description": "Proposal for improving climate adaptation strategies",
    "template_id": null,
    "status": "draft",
    "created_at": "2026-03-04T10:30:00.000Z",
    "updated_at": "2026-03-04T10:30:00.000Z",
    "user_id": "user_123",
    "user_email": "[e-mail]",
    "user_name": "John Doe",
    "uploaded_files": {},
    "text_inputs": {},
    "metadata": {},
    "completed_steps": [],
    "step_completion": {
      "step_1": {
        "completed": false,
        "has_rfp": false,
        "has_concept": false,
        "has_references": false
      },
      "step_2": {
        "completed": false,
        "rfp_analysis_status": "pending",
        "concept_analysis_status": "pending",
        "has_concept_document": false
      },
      "step_3": {
        "completed": false,
        "template_status": "pending",
        "has_template": false,
        "has_generated_content": false
      },
      "step_4": {
        "completed": false,
        "feedback_status": "pending",
        "has_feedback": false
      }
    }
  }
}

Notes

• One Draft Per User: The system enforces a single draft proposal per user. If you call this endpoint when a draft already exists, you’ll receive the existing draft instead of creating a new one.
• Proposal Code: The proposalCode is automatically generated in the format PROP-YYYYMMDD-XXXX where YYYYMMDD is the creation date and XXXX is a random suffix.
• Step Completion: The completed_steps array and step_completion object are computed based on actual data presence and provide a persistent tracking of proposal progress.
• User Information: The authenticated user’s ID, email, and name are automatically attached to the proposal.