AWS Organizations API Reference
API Reference (API Version 2016-11-28)


Deletes the specified policy from your organization. Before you perform this operation, you must first detach the policy from all OUs, roots, and accounts.

This operation can be called only from the organization's master account.

Request Syntax

{ "PolicyId": "string" }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.


The unique identifier (ID) of the policy that you want to delete. You can get the ID from the ListPolicies or ListPoliciesForTarget operations.

The regex pattern for a policy ID string requires "p-" followed by from 8 to 128 lower-case letters or digits.

Type: String

Pattern: ^p-[0-9a-zA-Z_]{8,128}$

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.


For information about the errors that are common to all actions, see Common Errors.


You don't have permissions to perform the requested operation. The user or role that is making the request must have at least one IAM permissions policy attached that grants the required permissions. For more information, see Access Management in the IAM User Guide.

HTTP Status Code: 400


Your account is not a member of an organization. To make this request, you must use the credentials of an account that belongs to an organization.

HTTP Status Code: 400


The target of the operation is currently being modified by a different request. Try again later.

HTTP Status Code: 400


The requested operation failed because you provided invalid values for one or more of the request parameters. This exception includes a reason that contains additional information about the violated limit:


Some of the reasons in the following list might not be applicable to this specific API or operation:

  • IMMUTABLE_POLICY: You specified a policy that is managed by AWS and cannot be modified.

  • INPUT_REQUIRED: You must include a value for all required parameters.

  • INVALID_ENUM: You specified a value that is not valid for that parameter.

  • INVALID_FULL_NAME_TARGET: You specified a full name that contains invalid characters.

  • INVALID_LIST_MEMBER: You provided a list to a parameter that contains at least one invalid value.

  • INVALID_PARTY_TYPE_TARGET: You specified the wrong type of entity (account, organization, or email) as a party.

  • INVALID_PAGINATION_TOKEN: Get the value for the NextToken parameter from the response to a previous call of the operation.

  • INVALID_PATTERN: You provided a value that doesn't match the required pattern.

  • INVALID_PATTERN_TARGET_ID: You specified a policy target ID that doesn't match the required pattern.

  • INVALID_ROLE_NAME: You provided a role name that is not valid. A role name can’t begin with the reserved prefix 'AWSServiceRoleFor'.

  • INVALID_SYNTAX_ORGANIZATION_ARN: You specified an invalid ARN for the organization.

  • INVALID_SYNTAX_POLICY_ID: You specified an invalid policy ID.

  • MAX_FILTER_LIMIT_EXCEEDED: You can specify only one filter parameter for the operation.

  • MAX_LENGTH_EXCEEDED: You provided a string parameter that is longer than allowed.

  • MAX_VALUE_EXCEEDED: You provided a numeric parameter that has a larger value than allowed.

  • MIN_LENGTH_EXCEEDED: You provided a string parameter that is shorter than allowed.

  • MIN_VALUE_EXCEEDED: You provided a numeric parameter that has a smaller value than allowed.

  • MOVING_ACCOUNT_BETWEEN_DIFFERENT_ROOTS: You can move an account only between entities in the same root.

HTTP Status Code: 400


The policy is attached to one or more entities. You must detach it from all roots, organizational units (OUs), and accounts before performing this operation.

HTTP Status Code: 400


We can't find a policy with the PolicyId that you specified.

HTTP Status Code: 400


AWS Organizations can't complete your request because of an internal service error. Try again later.

HTTP Status Code: 400


You've sent too many requests in too short a period of time. The limit helps protect against denial-of-service attacks. Try again later.

HTTP Status Code: 400


The following example shows how to delete a policy from an organization. The example assumes that you previously detached the policy from all entities:

Sample Request

POST / HTTP/1.1 Host: Accept-Encoding: identity Content-Length: 135 X-Amz-Target: AWSOrganizationsV20161128.DeletePolicy X-Amz-Date: 20160802T193159Z User-Agent: aws-cli/1.10.18 Python/2.7.8 Linux/2.6.18-164.el5 botocore/1.4.9 Content-Type: application/x-amz-json-1.1 Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20160802/us-east-1/organizations/aws4_request, SignedHeaders=content-type;host;user-agent;x-amz-date;x-amz-target, Signature=EXAMPLESIGabcdef1234567890abcdef1234567890abcdef123456EXAMPLESIG { "PolicyId": "p-examplepolicyid111" }

Sample Response

HTTP/1.1 200 OK x-amzn-RequestId: c7c142fb-58e7-11e6-a8d8-d5a10f646b91 Content-Type: application/x-amz-json-1.1 Content-Length: 0 Date: Tue, 02 Aug 2016 19:31:59 GMT

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: