Create Grouping
==================

Create a grouping.

Prerequisites
^^^^^^^^^^^^^

- Credentials as described in :doc:`/getting-started/authentication`

C#
^^

To create grouping, first create an instance of **CrayonApiClient** and get the token using **CrayonApiClient** instance.

Then call **Groupings.Create()** method to create grouping by passing the token and the instance of **Grouping**.

.. code-block:: c#
   :emphasize-lines: 30

   var grouping = new Grouping
   {
       Name = "Sample Grouping",
       InvoiceProfile = new ObjectReference
       {
           Id = 101,
           Name = "Standard Invoice Profile"
       },
       Organization = new ObjectReference
       {
           Id = 202,
           Name = "Sample Organization"
       },
       CreatedDate = DateTime.UtcNow,
       ModifiedDate = DateTime.UtcNow,
       IsDisabled = false,
       IsRemoved = false,
       InvoiceReference = "INV-00123"
   };

   var client = new CrayonApiClient("https://api.crayon.com/");
   var token = client.Tokens.GetUserToken(clientId, clientSecret, userName, password).GetData().AccessToken;
   var result = client.Groupings.Create(token, grouping);


Request
^^^^^^^

Request Syntax:

+---------+------------------------------------------------+
| Method  | Request URI                                    |
+=========+================================================+
| POST     | *https://api.crayon.com/api/v1/groupings/*    |
+---------+------------------------------------------------+

Request Body:

+-------------------+----------------------------------------------+-------------------------------------------------------------------------+
| Name              | Type                                         | Description                                                             |
+===================+==============================================+=========================================================================+
| Name              | string                                       | The name of the grouping                                                |
+-------------------+----------------------------------------------+-------------------------------------------------------------------------+
| InvoiceProfile    | ObjectReference                              | Reference to an invoice profile associated with the grouping.           |
+-------------------+----------------------------------------------+-------------------------------------------------------------------------+
| Organization      | ObjectReference                              | Reference to the organization this grouping belongs to.                 |
+-------------------+----------------------------------------------+-------------------------------------------------------------------------+
| CreatedDate       | DateTime                                     | Date and time when this grouping was created                            |
+-------------------+----------------------------------------------+-------------------------------------------------------------------------+
| ModifiedDate      | DateTime                                     | Date and time when this grouping was last modified.                     |
+-------------------+----------------------------------------------+-------------------------------------------------------------------------+
| IsDisabled        | bool                                         | ndicates whether the grouping is currently disabled.                    |
+-------------------+----------------------------------------------+-------------------------------------------------------------------------+
| IsRemoved         | bool                                         | Indicates if the grouping has been marked as removed.                   |
+-------------------+----------------------------------------------+-------------------------------------------------------------------------+
| InvoiceReference  | bool                                         | A custom invoice reference number or tag.                               |
+-------------------+----------------------------------------------+-------------------------------------------------------------------------+

Request Headers:

The following HTTP request headers are supported

+------------------+----------------+-----------------------------------------------------------------+
| Header           | Type           | Description                                                     |
+==================+================+=================================================================+
| Authorization    | string         | Required. The authorization token in the form Bearer <token>.   |
+------------------+----------------+----------------------------------------------+------------------+
| Accept           | string         | Specifies the request and response type, "application/json".    |
+------------------+----------------+----------------------------------------------+------------------+
| Content-Type     | string         | Specifies the media type of the resource, "application/json".   |
+------------------+----------------+----------------------------------------------+------------------+

Request Example:

::

	GET $"https://api.crayon.com/api/v1/groupings/{id}"
	Accept : application/json
	Content-Type: application/json 
	Authorization : Bearer < Token >

Response
^^^^^^^^

If successful, this method returns a single :doc:`/resources/Grouping` resource in the response body.

.. literalinclude:: /resources/_static/Grouping.json
        :language: json
	
Response success and error codes:

Each response comes with an HTTP status code that indicates success or failure and additional debugging information. Use a network trace tool to read this code, error type, and additional parameters.

+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Error Codes                    | Description                                                                                                                                                                                                                                                                               |
+================================+===========================================================================================================================================================================================================================================================================================+
| 200 Ok                         | The request has succeeded.                                                                                                                                                                                                                                                                |
+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 401 Unauthorized               | The request requires user authentication. If the request already included Authorization credentials, then the 401 (Unauthorized) status code means that authorization has been refused for those credentials. It is a non-retryable error condition.                                      |
+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 500 Internal Server Error      | Grouping fetching failed. Indicates that a generic error has occurred on the server.                                                                                                                                                                                                      |
+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+