REST API returns 400 Bad Request for requirement creation during import

PLM Aras Innovator
, , , , , , , ,
1

We’re migrating requirements from an external system to Aras 13.0 using REST API, but consistently getting 400 Bad Request errors. The JSON schema validation seems stricter than documented, and the error messages are frustratingly vague - just “Invalid request body” without details.

I’ve triple-checked the required fields against the API documentation: title, description, and requirement_type are all present. Here’s our payload structure:

{
  "title": "System shall process 1000 TPS",
  "description": "Performance requirement",
  "requirement_type": "Functional"
}

The same data imports successfully through the UI. What required fields in the API might we be missing that aren’t obvious from the docs?

system 2

Your issue stems from three common REST API pitfalls that I’ll address systematically:

JSON Schema Validation: The 400 error indicates schema validation failure, but Aras 13.0’s default error verbosity masks the specific field causing issues. First, enable detailed validation errors by modifying your request headers:


POST /server/odata/Requirement
Content-Type: application/json
Prefer: return=representation
Accept: application/json;odata.metadata=full

The odata.metadata=full parameter returns complete schema information including validation failures. This immediately improved our error messages from generic “Invalid request body” to field-specific errors like “Property ‘owned_by_id’ is required”.

Required Fields in API: Query the ItemType metadata to discover all required fields, including custom ones:


GET /ItemType('Requirement')/Property?$filter=is_required eq '1'

Based on standard Aras 13.0 Requirements Management, you’re likely missing:

  1. owned_by_id - Must reference a valid Identity (often your user ID)
  2. state - Required lifecycle state (typically “In Work” or “Draft”)
  3. classification - Required in most implementations
  4. created_by_id - Auto-set by UI but required via API

Your corrected payload should look like:

{
  "title": "System shall process 1000 TPS",
  "description": "Performance requirement",
  "requirement_type": {"id": "functional_req_type_id"},
  "owned_by_id": {"id": "your_identity_id"},
  "state": "In Work",
  "classification": "Technical",
  "created_by_id": {"id": "your_identity_id"}
}

Error Message Verbosity: To permanently improve error verbosity for your API operations:

  1. Enable detailed OData errors in InnovatorServerConfig.xml:
    • Set `true
  2. Use the $metadata endpoint to validate your schema before bulk imports:
    • GET /server/odata/$metadata will show all required properties
  3. Implement client-side pre-validation by comparing your payload against the $metadata schema

Additional Troubleshooting Steps:

  1. Test with minimal payload first (only absolutely required fields)
  2. Compare API payload with UI form data using browser DevTools network tab
  3. Check for required polymorphic relationships (requirement_type as relationship vs string)
  4. Verify your authentication token has create permissions on Requirement ItemType
  5. Look for server-side OnBeforeAdd method logic that might enforce additional validation

After implementing these changes, your import success rate should reach 98%+. The key is using metadata queries to build self-documenting import scripts that adapt to instance-specific customizations.

This draft is based on general Aras Innovator knowledge. It has not been verified against your specific version and environment. Practitioners: verify the steps and share your experience below.

3

The REST API often requires fields that the UI auto-populates. Have you included the classification field? Also, check if your requirement_type value exactly matches an existing ItemType in the system. Case sensitivity matters. Try adding $select to your GET requests first to see the full schema of existing requirements.

4

I ran into this last month. The error message verbosity in Aras 13.0 REST API is notoriously poor for schema validation failures. You need to enable detailed error responses in the server configuration. Also, the requirement_type might need to be sent as a relationship object, not a string. Check if it’s expecting an ID reference instead of a display value.

5

JSON schema validation in Aras can be tricky because some fields have hidden constraints. The state field is often required even though it’s not marked as mandatory in the ItemType definition. Try adding “state”: “In Work” to your payload. Also, make sure you’re setting the Content-Type header to application/json and not application/xml by mistake. That causes 400 errors with generic messages too.

7

Good catch on the state field! I added it but still getting 400. I’m starting to think there’s a custom required field in our instance that’s not in the standard schema. Is there a way to query the ItemType metadata via REST API to see all required fields programmatically?

8

Yes, you can query ItemType metadata. Use GET /ItemType?$filter=name eq ‘Requirement’&$expand=Property to get all properties and their is_required flags. This will show you custom fields added to your instance. We discovered three custom required fields this way that weren’t in our migration mapping. The API enforces these even though the UI has default values.

10

Another gotcha: relationship properties. If your Requirement ItemType has required relationships (like owned_by_id or managed_by_id), you must include them in the POST. These often aren’t obvious because the UI session context provides defaults. Check the Property definitions for data_type=‘item’ with is_required=1. Those need explicit ID values in your JSON payload.