> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create CrmOpportunityHistory

> Create a new CrmOpportunityHistory record.

A **CrmOpportunityHistory** records a single stage transition for a CRM opportunity. Each time an opportunity moves from one CRM stage to another, a history entry is created capturing the previous stage, the new stage, when the move happened, and which admin user triggered it.

Use this entity to audit the movement of opportunities across a CRM board over time. The History tab on an opportunity in the Nexudus UI displays these records.

## Authentication

<Note>
  This endpoint requires OAuth2 authentication. Include a valid bearer token in the `Authorization` header.
  The authenticated user must be a full unrestricted administrator or have the **`CrmOpportunityHistory-Create`** role.
</Note>

## Request Body

### Required Fields

<ParamField body="NewCrmBoardColumnId" type="integer" required>
  CRM stage the opportunity moved to.
</ParamField>

### Optional Fields

<ParamField body="CrmOpportunityId" type="integer">
  The opportunity this history entry belongs to.
</ParamField>

<ParamField body="OldCrmBoardColumnId" type="integer">
  CRM stage the opportunity moved from (null for the initial placement).
</ParamField>

<ParamField body="FromTime" type="string">
  When the opportunity entered the previous stage.
</ParamField>

<ParamField body="ToTime" type="string">
  When the opportunity left the previous stage and entered the new one.
</ParamField>

<ParamField body="UserId" type="integer">
  Admin user who triggered the stage transition (null if moved automatically).
</ParamField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    "https://spaces.nexudus.com/api/crm/crmopportunityhistories" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "NewCrmBoardColumnId": 0
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://spaces.nexudus.com/api/crm/crmopportunityhistories',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        NewCrmBoardColumnId: 0
      })
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://spaces.nexudus.com/api/crm/crmopportunityhistories',
      headers={
          'Authorization': 'Bearer YOUR_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'NewCrmBoardColumnId': 0
      }
  )

  data = response.json()
  ```
</CodeGroup>

## Response

### 200

<ResponseField name="Status" type="integer">
  HTTP status code. `200` on success.
</ResponseField>

<ResponseField name="Message" type="string">
  A human-readable message confirming the creation.
</ResponseField>

<ResponseField name="Value" type="object">
  Contains the `Id` of the newly created record.
</ResponseField>

<ResponseField name="WasSuccessful" type="boolean">
  `true` if the crmopportunityhistory was created successfully.
</ResponseField>

<ResponseField name="Errors" type="array">
  `null` on success.
</ResponseField>

```json Example Response theme={null}
{
  "Status": 200,
  "Message": "CrmOpportunityHistory was successfully created.",
  "Value": {
    "Id": 87654321
  },
  "OpenInDialog": false,
  "OpenInWindow": false,
  "RedirectURL": null,
  "JavaScript": null,
  "UpdatedOn": "2025-01-15T10:30:00Z",
  "UpdatedBy": "admin@example.com",
  "Errors": null,
  "WasSuccessful": true
}
```

### 400

<ResponseField name="Message" type="string">
  A summary of the validation error(s), in the format `PropertyName: error message`.
</ResponseField>

<ResponseField name="Value" type="any">
  `null` on validation failure.
</ResponseField>

<ResponseField name="Errors" type="object[]">
  Array of validation errors.

  <Expandable>
    <ResponseField name="AttemptedValue" type="any">
      The value that was submitted for the field, or `null` if missing.
    </ResponseField>

    <ResponseField name="Message" type="string">
      The validation error message.
    </ResponseField>

    <ResponseField name="PropertyName" type="string">
      The name of the property that failed validation.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="WasSuccessful" type="boolean">
  `false` when the request fails validation.
</ResponseField>

```json Example Response theme={null}
{
  "Message": "Name: is a required field",
  "Value": null,
  "Errors": [
    {
      "AttemptedValue": null,
      "Message": "is a required field",
      "PropertyName": "Name"
    }
  ],
  "WasSuccessful": false
}
```